Weapon Switching

Weapon switching lets a character carry several weapons and change between them. A change takes time: the old weapon is put away, then the new one is drawn, and nothing can attack meanwhile. Each weapon keeps its own wait after an attack, so swapping away and back never skips it.

Also called: Weapon swap, Weapon wheel, Quick swap.

A fox scavenger on a floating metal platform swaps weapons mid-motion, a violet crossbow breaking into glittering cubes in one hand while a teal chain-whip is half drawn in the other, with three glowing holders beside it. — Zurnibble Yard, an invented low-poly junkyard shooter. Invented game, image generated with AI.

Paste this to your AI

Copy it into Claude, Cursor or ChatGPT. It already has good values and the usual mistakes in it.

Add "Weapon Switching" to my game.

What it should do: Carrying several weapons gives the player choices in the middle of a fight, and the time a swap takes makes each choice cost something.

Build it exactly as this state machine. First check that it fits my game, then build it like this:

```mermaid
stateDiagram-v2
  [*] --> ready
  ready: Weapon ready
  lowering: Putting away
  raising: Drawing
  bare: Empty hands
  ready --> lowering: switch asked for
  lowering --> raising: old weapon is away
  raising --> ready: new weapon is drawn
  ready --> bare: weapon is lost
  lowering --> bare: target is lost
  raising --> bare: weapon is lost
  bare --> raising: a weapon is drawn
```

Use these starting values:
- slots: 3
- lowerTime: 0.2 s
- raiseTime: 0.35 s
- attackTime: 0.5 s

Watch out for these common mistakes:
- Swapping to skip the wait: Tell your AI: keep the wait on each weapon. A swap does not change it, and it keeps running while the weapon is put away.
- Empty slots: Tell your AI: when stepping, skip empty slots and wrap around. Asking for an empty slot directly does nothing.
- Stepping quickly: Tell your AI: while a switch is under way, step on from the weapon being switched to.
- A weapon taken away: Tell your AI: if the weapon in hand is gone, go to empty hands that same tick, then draw the lowest slot that has a weapon.
- An attack and a swap in the same moment: Tell your AI: decide from how the tick began. The attack goes out first, and then the swap starts.

Do not change anything else in the game. Do not claim anything without proof: model what it takes, and show me what your solution rests on and how I can see that it works. If you cannot show something, say you do not know. When you are done, tell me in plain words how to try it.

Or skip this and connect the MCP: your AI then finds all of this by itself.Connect the MCP

What it does

Carrying several weapons gives the player choices in the middle of a fight, and the time a swap takes makes each choice cost something.

How it runs, as a diagram

Everything it can be in, and what moves it on. Your AI builds from exactly this.

How it runs, as a diagram

Weapon ready → Putting away: switch asked for
Putting away → Drawing: old weapon is away
Drawing → Weapon ready: new weapon is drawn
Weapon ready → Empty hands: weapon is lost
Putting away → Empty hands: target is lost
Drawing → Empty hands: weapon is lost
Empty hands → Drawing: a weapon is drawn

Good starting values

Value	Start with	What it changes
slots	3	How many weapons the character can carry. Three is enough to choose between and few enough to remember.
lowerTime	0.2 s	Time to put the weapon in hand away. Short, because the player has already decided.
raiseTime	0.35 s	Time to draw the new weapon. The longer half of a swap, so the wait is felt before the new weapon can be used.
attackTime	0.5 s	The wait after an attack before the same weapon can attack again. Shorter than a full swap, so a swap is a real cost but not a punishment.

What usually goes wrong

Swapping to skip the wait

If the wait after an attack belongs to the character instead of the weapon, or is reset by a swap, the player can attack, swap away and back, and attack again, getting around the pace the weapon was meant to have.

Fix: Tell your AI: keep the wait on each weapon. A swap does not change it, and it keeps running while the weapon is put away.

Empty slots

Stepping to the next weapon can land on an empty slot, so the player puts away a weapon, draws nothing, and stands with empty hands.

Fix: Tell your AI: when stepping, skip empty slots and wrap around. Asking for an empty slot directly does nothing.

Stepping quickly

If each step counts from the weapon in hand, two quick presses to go two weapons along end on the first one, and a mouse wheel that scrolls fast feels broken.

Fix: Tell your AI: while a switch is under way, step on from the weapon being switched to.

A weapon taken away

If the weapon in hand is dropped, stolen or used up, the game keeps pointing at a slot that holds nothing, and the character attacks with a weapon that is not there.

Fix: Tell your AI: if the weapon in hand is gone, go to empty hands that same tick, then draw the lowest slot that has a weapon.

An attack and a swap in the same moment

If the swap is handled first, the attack the player pressed is thrown away. If both are mixed up, the weapon might attack and be put away halfway through.

Fix: Tell your AI: decide from how the tick began. The attack goes out first, and then the swap starts.

How to check it works

Your character holds the weapon in slot 0. Ask for slot 2: After about 0.55 seconds, 0.2 to put away and 0.35 to draw, slot 2 is in hand and ready.
Your character is switching weapons. Press attack all the time: No attack comes until the new weapon is ready.
Your character holds a ready weapon. Press attack twice at once, and then again after 0.5 seconds: Only the first and the last press attack.
Your weapon in slot 0 has just attacked and its wait is 3 seconds. Switch to slot 1 and back to slot 0: Slot 0 is ready again, but its wait has only gone down by the time that passed, and attacking is still refused.
Slot 1 is empty and slots 0 and 2 hold weapons. Step to the next weapon from slot 0, and from slot 2: The first step goes to slot 2 and the second wraps around to slot 0.
Your character holds slot 0. Step to the next weapon twice in a row, quickly: The character ends with slot 2 in hand, not slot 1.
Your character holds slot 0. Ask for slot 0: Nothing happens.
Slot 1 is empty. Ask for slot 1, for a slot that does not exist, or for a slot below zero: Nothing happens each time.
Your character holds slot 0, and the weapon is taken away while slots 1 and 2 hold weapons. Wait a moment: The hands are empty first, then the lowest slot with a weapon is drawn.
Your character is drawing slot 1. Ask for slot 2: The request waits, slot 1 gets ready, and then the swap to slot 2 starts.
Your character is drawing slot 1 and a request for slot 2 is waiting. Ask for slot 1: The waiting request is gone.
Your character holds a ready weapon. Press attack and ask for another slot in the same moment: The weapon attacks, starts its wait, and the swap begins.
Your character is drawing slot 1. The weapon in slot 1 is taken away: The character has empty hands.

Works well with

Ammo and Reload: Decide whether the reload starts again or carries on from where it was when the weapon returns. Either is fine, but the swap should never finish a reload for free. Stop a reload when the weapon is put away.
Hotbar: The slots here can be the bar's slots. Keep the numbers the player presses and the slots the weapons sit in as one list.
Equipment Slots: An equipped weapon is one the character owns. Let the equipment list tell this mechanic which slots are filled.

Clashes with Combo System: A chain in the middle of a combo wants the same weapon for the next hit, and a swap throws the chain away. Refuse a swap while a chain is under way, or end the chain when a swap starts, and say which in the game.

Common questions

what do i tell my ai to add weapon switching

Paste this: Add weapon switching with three slots. Switching puts the old weapon away for 0.2 seconds and draws the new one for 0.35 seconds, with no attacks meanwhile. Each weapon keeps its own 0.5 second wait after an attack, and a swap never resets it. Stepping skips empty slots and wraps around, and quick steps go on from the weapon being switched to.

how long should a weapon swap take

A little over half a second is a good start. Under a quarter of a second makes swapping free, and over a second makes players stick to one weapon.

should each weapon have its own cooldown

Yes. If the wait belongs to the character, a swap can be used to skip it, and if a swap resets it, swapping becomes a way to attack faster.

what happens when the weapon in hand is lost

The hands go empty that same moment and the lowest slot with a weapon is drawn. Pointing at a slot with nothing in it leads to attacks with a weapon that is not there.

Where it comes from

We could not find a reliable origin for this one yet.

Where this mechanic comes from has not been researched yet.

Games are named only as references. Names and marks belong to their owners, and nothing here is endorsed by them.

What was checked

17 tests pass on the reference code.
The state diagram was checked against the code, at the default values and at every listed low and high value.

This is what separates the blueprint from a catalogue entry: the values on this page come from code that runs.

Your AI gets the code

Tested example code comes through the Spielerando connection, so your AI can use it right away. How to connect it