Projectiles

A projectile is a shot that is fired, flies and ends. It leaves at a set speed, may fall in an arc, and ends when it hits its last target, reaches the ground or runs out of time. Look for hits along the whole path of each frame, so fast shots cannot skip a target.

Also called: Bullets, Arrows, Shots, Missiles.

A small snail archer on a mossy stump has fired a glowing seed in a long arc, which bursts through a paper-lantern jellyfish in a ring of pink petals, a second jellyfish waiting ahead on the same curve. — Fennelwick Volley, an invented garden defence game. 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 "Projectiles" to my game.

What it should do: Shots let the player hit what is far away, and give the enemy something to dodge. A shot you can see coming, that always hits what it touches, feels fair, and that is what this page is about.

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
  flying: In flight
  spent: Hit
  landed: On the ground
  fizzled: Out of time
  ready --> flying: is fired
  flying --> spent: hits its last target
  flying --> landed: reaches the ground
  flying --> fizzled: time runs out
  spent --> [*]
  landed --> [*]
  fizzled --> [*]
```

Use these starting values:
- speed: 20 units/s
- gravity: 10 units/s²
- lifetime: 2 s
- pierce: 0
- radius: 0.15 units

Watch out for these common mistakes:
- A fast shot skips a thin target: Tell your AI: check the whole path the shot took during the frame, from where it started to where it ended, and take the first target along that path.
- A shot that passes through a target hits it again and again: Tell your AI: remember which targets the shot has hit, and never count the same one twice.
- A target right in front of the weapon: Tell your AI: a shot that starts a frame inside a target hits it at once, on that frame.
- An arc that changes with the frame rate: Tell your AI: work out the position from the time with the exact formula for a falling body, not by adding small steps, so any frame length lands in the same place.
- The ground or the end of time beats a hit that came first: Tell your AI: cut the frame short at the ground or at the end of time, look for hits along that part of the path, and only then end the shot.

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

Shots let the player hit what is far away, and give the enemy something to dodge. A shot you can see coming, that always hits what it touches, feels fair, and that is what this page is about.

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 → In flight: is fired
In flight → Hit: hits its last target
In flight → On the ground: reaches the ground
In flight → Out of time: time runs out

Good starting values

Value	Start with	What it changes
speed	20 units/s	How fast the shot leaves. Twenty crosses a room in about a second, so the player can see it coming and still has to move to dodge it. Much faster, and the shot is hard to see at all.
gravity	10 units/s²	How fast the shot drops. A gentle arc rewards aiming a little above the target. Zero gives a straight bolt that is easier to aim.
lifetime	2 s	How long the shot flies before it fizzles out. Long enough to cross the screen, short enough that missed shots do not pile up.
pierce	0	How many targets the shot passes through before it stops. Zero means it stops at the first. Piercing is a power the player should earn, so the usual shot has none.
radius	0.15 units	Half the width of the shot. It is added to the size of every target, so a near miss that looks like a hit counts as one.

What usually goes wrong

A fast shot skips a thin target

The game only checks whether the shot overlaps a target where it stands at the end of each frame. A fast shot moves further than the target is wide in one frame and passes straight through it.

Fix: Tell your AI: check the whole path the shot took during the frame, from where it started to where it ended, and take the first target along that path.

A shot that passes through a target hits it again and again

A shot that is meant to pass through targets overlaps the same target for many frames and hits it on every one of them, so it does ten times the damage.

Fix: Tell your AI: remember which targets the shot has hit, and never count the same one twice.

A target right in front of the weapon

A target stands so close that the shot starts inside it. A check that looks for a shot entering the target never sees it enter, so the shot flies through it without a hit.

Fix: Tell your AI: a shot that starts a frame inside a target hits it at once, on that frame.

An arc that changes with the frame rate

The shot is moved by adding a drop on every frame. On a slow machine the arc is flatter and the shot lands further away than on a fast one, so the same shot is a hit on one machine and a miss on another.

Fix: Tell your AI: work out the position from the time with the exact formula for a falling body, not by adding small steps, so any frame length lands in the same place.

The ground or the end of time beats a hit that came first

In the frame where a shot reaches the ground or runs out of time, the game ends the shot first and never looks for a target it touched just before. The player sees a clear hit that does nothing.

Fix: Tell your AI: cut the frame short at the ground or at the end of time, look for hits along that part of the path, and only then end the shot.

How to check it works

A shot that is ready. You fire it level, straight up and at a slant: It leaves at exactly the set speed in each direction, and only starts to move on the next frame.
A shot that is already flying. You fire again: Nothing changes, and a new shot needs a new projectile.
The same shot fired at a slant. It is played with frames from a fifteenth to a two-hundred-and-fortieth of a second: It lands in exactly the same place every time.
A straight shot with two targets in its way. It flies: It hits the nearer one and stops there.
A very fast shot, long frames and a thin target in the way. It flies: It hits the target.
A straight shot and a target well above its path. It flies: It hits nothing and fizzles out.
A target that overlaps the point the shot starts from. The shot is fired: It hits the target on the first frame it moves.
A shot that can pass through two targets and four targets in a row. It flies: It hits the first three in order along its path and is spent at the third.
A shot that can pass through three targets and one very large target around its path. It flies right through the large one: The large target is hit once.
A level shot fired from above the ground with gravity on. It falls: It lands at height zero, at the place the exact arc gives.
A straight shot with nothing in its way. Its time runs out: It stops after exactly its lifetime, at exactly speed times lifetime away, whatever the frames.
A target just inside the shot's reach, and another just beyond it, with long frames. The shot flies: It hits the first one and misses the second.
A target just before the point where the shot reaches the ground, and long frames. The shot flies: It hits the target. Without the target it lands.
An aim that is not a number, or targets with a broken place or size. You fire and fly: The shot is not fired for a bad aim, and broken targets are never hit.
A shot that has hit, landed or fizzled. You fire again or put a target on it: Nothing changes.

Works well with

Health and Damage: A shot only says what it touched. The health decides what that does, including the short protection after a hit. Hand each target in the last hits to the health, one by one.
Ammo and Reload: A weapon that fires many shots keeps one projectile for each. The ammunition decides whether a shot is made at all. Check the ammunition before the shot is fired.
Critical Hits: A shot that passes through four targets can crit on one and not the others. A single roll for the whole shot makes all or none of them crits. Roll once for each target a shot hits, not once for the shot.

Common questions

what do i tell my ai to add shooting projectiles

Paste this: Add projectiles: a shot leaves at twenty units a second in the aimed direction and falls with a little gravity. Every frame, look for targets along the whole path the shot took, not where it ends up, and hit the nearest first. It ends when it hits its last target, reaches the ground or has flown two seconds. Never hit the same target twice. Work out the arc from the time, not by adding small steps.

why do fast bullets go through enemies

The game checks for an overlap only where the bullet is at the end of each frame. A fast bullet moves further than the enemy is wide in one frame. Check the whole path of the frame instead.

how do i make a piercing shot without hitting an enemy ten times

Keep a list of the enemies the shot has hit, and skip any that are on it. Then set how many it may pass through and end the shot when it has hit one more than that.

why does my arrow land in a different place on slower computers

Because the drop is added on every frame, and fewer frames give a flatter arc. Work out the position from the time with the formula for a falling body, and every machine lands in the same place.

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

25 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