Light gun

What it does

createGun builds a gun from data. Each step you give it the aim, as an absolute pointer, a touch tap or a stick, and the trigger, special and reload buttons. The crosshair can be smoothed and kicked by recoil, and the gun knows when it points off the screen. Triggers fire single shots, automatic fire at a rate or bursts, with cooldowns. A weapon carries its damage, spread and pellets, piercing, blast radius and travel time, a magazine with spares or a simple stock, the ways it reloads, slow fire when empty, and timed boosts.

Shots resolve against a HitWorld, which answers "what is under this point" in the order you want occlusion to work. screenWorld takes 2D targets with circle and rectangle regions ordered by depth, so a head is hit before a body, a hostage in front of a soldier takes the shot, and window glass stops a bullet before the man behind it. rayWorld wraps a 3D ray pick, and layeredWorld puts a 2D overlay in front of a 3D scene. Regions carry body parts with damage multipliers, shields that block, and protected kinds that report a penalty after free warnings.

The gun does not apply damage: it drains hit events with the target, region, part and damage, and you apply them. Alongside come blocked, protected-hit, miss, reload and fx cues for muzzle flashes, recoil shakes, blast shakes and screen flashes. Statistics count shots, hits, misses, blocks, protected hits, parts and streaks within a combo window.

Features

• Any aiming device — an absolute pointer, a finger with no smoothing, or a stick moving the sight, with smoothing, clamping and felt recoil.
• Triggers — single, automatic at a rate, or bursts, with cooldowns and presses shorter than a step latched.
• Weapons as data — damage, spread, up to 64 pellets, piercing, blast radius, travel time to impact and a launch point.
• Ammunition and reloads — magazines and spares or a stock, reloads by button, by shooting off the screen or automatically, slow fire when out, and boosts for faster or free rounds.
• Occlusion you control — front-to-back hit candidates in 2D by depth or in 3D by distance, and layered worlds.
• Hit regions — circles and rectangles with body parts, damage multipliers, shields, and regions a shot passes through.
• Protected targets — hostages and civilians that take the shot instead of damage, with warnings and penalties reported for your game to apply.
• Accuracy and streaks — shots, hits, misses, blocks, parts and combos, and an accuracy figure.
• Presenter cues — muzzle flash, recoil and blast shake and screen flash as events and state, plus an off-screen reload band you can hint at.
• Deterministic — fixed 1/60 s steps with snapshot and restore.

Good for

• Light-gun shooters in the style of Operation Wolf, with an automatic weapon, magazines and rockets.
• Cover shooters in the style of Time Crisis, with a pedal reload and a gun that is not ready while in cover.
• Rail shooters in the style of The House of the Dead, with off-screen reloads, headshots and scientists to spare.
• Shooting galleries and carnival ranges, and duck shoots in the style of Duck Hunt.
• Turret crosshairs over a 3D scene, using a ray pick.
• Touch and mouse games where a tap or click is the shot.

Make it yours

The view size, the aim's smoothing, stick speed and clamp, every weapon, the primary and special weapon, the damage multipliers for each part, the protection rules and penalties, and the combo window are all part of the gun's definition. Two players are two guns.

Very different guns come from the same few fields. A cover-shooter pistol is a six-round magazine with unlimited spares, a button reload, and setReady(false) while the player hides. A rail-shooter pistol reloads by shooting into an edge band of the screen, triples damage on the head and keeps a one-second combo. A shotgun is six pellets in a spread; a sniper rifle pierces two targets and kicks the sight; an Uzi fires automatically from 30-round magazines, keeps firing slowly when out, and sits beside a rocket with a blast radius and a flight time.

A quick look

An automatic primary and a rocket special, resolved against 2D targets, with hits applied by your game:

const LG = game.lightGun;
const gun = LG.createGun({
  view: { w: 240, h: 240 },
  weapons: [
    { id: 'uzi', trigger: 'auto', rate: 8, magazine: 30, magazines: 6, reload: { modes: ['auto'], time: 0.3 } },
    { id: 'rocket', stock: 5, radius: 34, travel: 0.45, damage: 10 },
  ],
  primary: 'uzi', special: 'rocket',
});
const world = LG.screenWorld(() => targets);
gun.tick(dt, { x, y, trigger, special, reload }, world);
for (const e of gun.drain()) if (e.type === 'hit') applyDamage(e.target, e.damage, e.part);

Works with

• shooting-gallery — whole 2D gallery games built on this gun, with stages, actors and quotas.
• cover-shooter — rail and cover games whose pistol is this gun, resolved by a ray over their route.
• rail-route — a 3D ray pick to wrap with rayWorld.
• aim-3d and projectile-patterns — for twin-stick aiming instead of a crosshair.

Good to know

• One crosshair per gun; spread is uniform in a disc and there is no ballistic drop.
• The 2D world tests circles and axis-aligned rectangles, so rotated art uses several regions.
• Penalties for protected hits are reported, not applied: your game decides what they cost.
• A browser pointer cannot leave the page, so shooting off the screen is an edge band of the view.