Fuel Gauge

A fuel gauge is a tank that an engine burns down and that never fills by itself. The engine burns a little just by running and more with the throttle. On the last stretch it gives only part of its power as a warning. At zero it stops and needs fuel and a fresh start.

Also called: Fuel tank, Fuel meter, Gas gauge, Jetpack fuel, Energy tank.

A frog pilot in a small blue hover-skiff glides over a crystal salt flat with a sputtering thruster, while the fuel tube on the hull is almost empty and a pump tower with a green beacon shows far ahead. — Glimmerplank Run, an invented hover-racing adventure. 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 "Fuel Gauge" to my game.

What it should do: Fuel turns every flight or drive into a trip with a budget. The player plans how far to go, where to refill, and when to push on, so reaching a pump or a pickup feels like a real relief.

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

```mermaid
stateDiagram-v2
  [*] --> off
  off: Engine off
  run: Running
  reserve: On reserve
  dry: Tank empty
  off --> run: engine starts
  off --> reserve: starts on reserve
  off --> dry: starts and runs dry
  run --> reserve: reserve begins
  run --> off: engine switched off
  run --> dry: tank runs dry
  reserve --> run: fuel above reserve
  reserve --> off: engine switched off
  reserve --> dry: tank runs dry
  dry --> off: fuel comes in
  dry --> run: fuel in and started
  dry --> reserve: little fuel and started
```

Use these starting values:
- tankSize: 60 units
- burnRate: 4 units/s
- idleBurn: 0.2 units/s
- reserveFraction: 0.15 share of full
- limpPower: 0.6 share of full

Watch out for these common mistakes:
- Free push on the last drop: Tell your AI: give the engine only the share of power that the burned fuel could pay for in that moment.
- The tank goes below zero: Tell your AI: never burn more than the tank holds, and stop the engine when it reaches exactly zero.
- The engine restarts by itself: Tell your AI: after the engine cuts out, it stays off until the player starts it again.
- A pickup is used up on a full tank: Tell your AI: report how much fuel the tank took, and take only that much from the can.
- The tank runs out with no warning: Tell your AI: before the tank is empty, add a reserve where the engine gives less power and the gauge warns, so the player has a few seconds to act.

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

Fuel turns every flight or drive into a trip with a budget. The player plans how far to go, where to refill, and when to push on, so reaching a pump or a pickup feels like a real relief.

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

Engine off → Running: engine starts
Engine off → On reserve: starts on reserve
Engine off → Tank empty: starts and runs dry
Running → On reserve: reserve begins
Running → Engine off: engine switched off
Running → Tank empty: tank runs dry
On reserve → Running: fuel above reserve
On reserve → Engine off: engine switched off
On reserve → Tank empty: tank runs dry
Tank empty → Engine off: fuel comes in
Tank empty → Running: fuel in and started
Tank empty → On reserve: little fuel and started

Good starting values

Value	Start with	What it changes
tankSize	60 units	How big the full tank is. With the starting burn it gives about 14 seconds at full throttle, long enough for a real climb and short enough that the player watches the gauge.
burnRate	4 units/s	How much the engine burns each second at full throttle. Together with the tank size it sets how far the player gets on one fill.
idleBurn	0.2 units/s	How much the engine burns just by running with no throttle. A small amount stops the player from leaving the engine on for free while waiting.
reserveFraction	0.15 share of full	The share of the tank that counts as reserve. About a seventh gives the player a few seconds to find a pump after the warning.
limpPower	0.6 share of full	The most power the engine gives on reserve. Less than full makes the warning felt, and more than zero keeps the player from crashing at the exact moment it starts.

What usually goes wrong

Free push on the last drop

The tank holds a sliver, but the engine gives full power for the whole moment, as if the fuel had been enough. Over many moments that is a lot of free flying.

Fix: Tell your AI: give the engine only the share of power that the burned fuel could pay for in that moment.

The tank goes below zero

A slow moment, such as a hiccup in the game, asks for more fuel than is left. The tank ends up below zero, and the gauge draws backwards or the game stops.

Fix: Tell your AI: never burn more than the tank holds, and stop the engine when it reaches exactly zero.

The engine restarts by itself

The player picks up fuel while the throttle is held down, and the engine springs back to life with no start. It feels like a glitch, and a pickup near a cliff can push the player over.

Fix: Tell your AI: after the engine cuts out, it stays off until the player starts it again.

A pickup is used up on a full tank

The player drives over a fuel can with a nearly full tank. The tank takes what fits, but the can is gone, and the rest of its fuel is lost.

Fix: Tell your AI: report how much fuel the tank took, and take only that much from the can.

The tank runs out with no warning

The gauge looks fine and the next moment the engine dies. The player feels cheated, because there was nothing to react to.

Fix: Tell your AI: before the tank is empty, add a reserve where the engine gives less power and the gauge warns, so the player has a few seconds to act.

How to check it works

A full tank of 60 and a running engine. the throttle is held at full for 1 second: the tank shows 55.8, because 4 burned for the throttle and 0.2 for running, and at half throttle it shows 57.8.
A full tank and a running engine. the throttle stays at zero for 4 seconds: the tank shows 59.2.
A tank of 30 and an engine that is off. the player holds the throttle for 10 seconds: the tank still shows 30 and the engine gives no power.
A tank of 9, which is the reserve. the throttle is held at full: the engine gives 0.6 and not more, and with 9.5 in the tank it gives the full 1.
A running engine with half a unit left. the throttle is held at full: the tank goes to exactly zero, the engine stops, and it gave only part of the push because the fuel covered part of the moment.
An engine that has cut out on an empty tank. 30 units of fuel arrive while the throttle is held: the tank holds 30 and the engine stays off, until the player starts it.
An empty tank. the player tries to start the engine: nothing happens and the engine stays off.
A tank of 55 and a can with 20. the engine is off and the can is poured in: the tank stops at exactly 60 and the game is told that only 5 were taken.
A tank of 30. a fuel offer of minus 10, zero, or something that is not a number comes in: the tank stays at 30 and nothing is taken.
A running engine. start and stop are asked in the same moment: the engine is off and burns nothing.

Works well with

Stamina System: A jetpack or a mount can burn fuel for the push and stamina for the player, so the player manages two bars. Make clear in the look which one just ran out. Check the fuel first, then the stamina.

Common questions

how does a fuel gauge work in a game

A tank goes down while the engine runs and never fills by itself. The player refills it from pickups or pumps. At zero the engine stops.

what is a fuel reserve in game design

It is the last part of the tank, where the engine gives less power as a warning. It gives the player a few seconds to react before the engine dies.

how much fuel should a jetpack have

Start with about 14 seconds of full throttle. Shorter makes the jetpack a hop, longer makes the tank a formality.

what do i tell my ai to add a fuel gauge

Paste this: Add a fuel gauge. The engine burns a little when running and more with the throttle. At 15 percent left, limit its power to 60 percent. At zero it cuts out and only restarts when the player starts it again after refuelling. A pickup fills 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

19 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