Ammo and Reload

Ammo has two stores: the rounds in the weapon and the rounds in reserve. A shot uses one round, no faster than the fire interval. A reload takes time and moves rounds from the reserve only at its end, so stopping it halfway loses nothing. A full reserve turns extra pickups away.

Also called: Ammunition, Magazine and reserve, Reload system, Ammo count.

A small helmeted frog courier crouches on a rooftop swapping a glowing dart cartridge into its launcher while the empty one tumbles away, with a rack of darts behind it. — Coilhop Couriers, an invented two-colour rooftop 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 "Ammo and Reload" to my game.

What it should do: Ammo makes shooting a series of small decisions: fire now or save rounds, reload now or risk running dry in the middle of a fight.

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

```mermaid
stateDiagram-v2
  [*] --> ready
  ready: Ready to fire
  reloading: Reloading
  empty: Weapon empty
  dry: Out of ammo
  ready --> ready: shoots or waits
  ready --> reloading: reload starts
  ready --> empty: last round, spare left
  ready --> dry: last round, none spare
  reloading --> reloading: reload goes on
  reloading --> ready: done or cancelled
  reloading --> empty: cancelled, still empty
  empty --> empty: waits
  empty --> reloading: reload starts
  dry --> dry: nothing to fire
  dry --> empty: picks up ammo
  dry --> reloading: picks up, reloads
```

Use these starting values:
- magazineSize: 12 rounds
- reserveMax: 120 rounds
- reloadTime: 1.6 s
- fireInterval: 0.25 s

Watch out for these common mistakes:
- Rounds move at the start of a reload: Tell your AI: move the rounds only when the reload finishes. Stopping it halfway changes nothing.
- A reload throws away the rounds still in the weapon: Tell your AI: a reload only tops up. It takes from the reserve just what is missing, and the total stays the same.
- A held trigger fires on every tick: Tell your AI: count the wait between shots in seconds, and fire at most once per moment.
- Rounds picked up beyond the limit vanish: Tell your AI: take only what fits, report the rest, and leave it where it was so the player can come back for it.
- A pickup during a reload: Tell your AI: decide how many rounds move at the moment the reload ends, from the reserve as it is then.
- Pressing reload again during a reload: Tell your AI: ignore reload presses while a reload runs.
- A trigger pull with no ammo does nothing: Tell your AI: report the empty click so the game can play a sound. And when only the weapon is empty, start a reload instead.

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

Ammo makes shooting a series of small decisions: fire now or save rounds, reload now or risk running dry in the middle of a fight.

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

Ready to fire → Ready to fire: shoots or waits
Ready to fire → Reloading: reload starts
Ready to fire → Weapon empty: last round, spare left
Ready to fire → Out of ammo: last round, none spare
Reloading → Reloading: reload goes on
Reloading → Ready to fire: done or cancelled
Reloading → Weapon empty: cancelled, still empty
Weapon empty → Weapon empty: waits
Weapon empty → Reloading: reload starts
Out of ammo → Out of ammo: nothing to fire
Out of ammo → Weapon empty: picks up ammo
Out of ammo → Reloading: picks up, reloads

Good starting values

Value	Start with	What it changes
magazineSize	12 rounds	How many rounds the weapon holds before it must be reloaded. A small number makes reloading a frequent pause, a large one makes it a rare event.
reserveMax	120 rounds	How many spare rounds can be carried. Ten magazines is enough to feel safe without feeling rich. Zero means no spares at all.
reloadTime	1.6 s	How long a reload takes. Long enough to be a risk in a fight, short enough not to be a chore. It is never zero, because an instant reload would make the pause pointless.
fireInterval	0.25 s	The wait between two shots, so four shots a second. It is never zero, and a single moment of the game never fires twice, however long it lasts.

What usually goes wrong

Rounds move at the start of a reload

The rounds jump into the weapon when the reload begins. Switching weapon halfway then gives a full magazine for free, or makes the rounds vanish from both stores.

Fix: Tell your AI: move the rounds only when the reload finishes. Stopping it halfway changes nothing.

A reload throws away the rounds still in the weapon

The weapon still holds 5 rounds, the player reloads, and the game fills it from the reserve without counting them. 5 rounds disappear, or 5 appear.

Fix: Tell your AI: a reload only tops up. It takes from the reserve just what is missing, and the total stays the same.

A held trigger fires on every tick

Holding the button fires once per frame. On a fast screen the weapon shoots twice as fast as on a slow one.

Fix: Tell your AI: count the wait between shots in seconds, and fire at most once per moment.

Rounds picked up beyond the limit vanish

The reserve is nearly full and the player picks up a crate of 40. The crate is used up, yet only 5 fit, and 35 rounds are gone without a word.

Fix: Tell your AI: take only what fits, report the rest, and leave it where it was so the player can come back for it.

A pickup during a reload

The reload is already running when the player grabs rounds in the middle of it. If the game fixed the amount at the start, the new rounds sit unused until the next reload.

Fix: Tell your AI: decide how many rounds move at the moment the reload ends, from the reserve as it is then.

Pressing reload again during a reload

Each press starts the reload from the top. A nervous player taps the button and never finishes.

Fix: Tell your AI: ignore reload presses while a reload runs.

A trigger pull with no ammo does nothing

The player pulls the trigger with an empty weapon and an empty reserve, and nothing at all happens. It feels like a broken button.

Fix: Tell your AI: report the empty click so the game can play a sound. And when only the weapon is empty, start a reload instead.

How to check it works

Your weapon is full with 12 rounds. you pull the trigger: a shot is fired, the weapon holds 11 and the reserve is unchanged.
You hold the trigger for one second at four shots a second. one second goes by: exactly four shots are fired.
Your weapon and your reserve are both empty. you pull the trigger: no shot is fired and the game reports the empty click.
Your weapon is empty but you have spare rounds. you pull the trigger: a reload starts and no shot is fired.
Your weapon holds 2 rounds and you have 100 spare. you reload and wait: nothing changes during the reload, and at the end the weapon holds 12 and the reserve 90.
Your weapon is empty and you have only 5 spare rounds. you reload: the weapon holds 5 and the reserve is empty.
Your weapon is full. you press reload: no reload starts.
You are halfway through a reload with 3 in the weapon and 40 spare. you stop the reload: the weapon still holds 3 and the reserve still holds 40.
You are reloading. you hold the trigger: no shot is fired.
Your reserve holds 115 of 120. you pick up 30 rounds: the reserve holds 120 and the game reports 25 left over.

Works well with

Inventory System: Reserve limits and the left-over report tell the inventory what to keep on the ground. Let the inventory hold the ammo as an item, and let this mechanic decide how it is spent.
Ability Cooldowns: Both pace the player with waiting, so give them different rhythms or they blur together. Use the cooldown for abilities and this mechanic for the weapon.

Common questions

how does ammo and reloading work in games

A weapon holds a few rounds and you carry more in reserve. Shooting uses the weapon's rounds. Reloading takes a moment and then refills the weapon from the reserve.

how long should a reload take

Start with about 1.6 seconds. Under a second it is a formality, over three seconds it becomes a punishment unless the weapon is meant to be heavy.

what should happen when you cancel a reload

Nothing should be lost and nothing gained. Keep the rounds where they were until the reload is finished, and cancelling is safe and simple.

what do i tell my ai to add ammo and reloading

Paste this: Add ammo. The weapon holds 12 rounds and the reserve 120. A shot every 0.25 seconds at most. A reload takes 1.6 seconds and moves the rounds at the end, so cancelling loses nothing. Pickups take only what fits.

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

20 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