Log inGet started
Package

projectileKit.package

README.md

projectileKit.api

The kit's public entry point: pooled projectiles, continuous beams, lightning arcs, puffs, bursts and rings. Shots are plain data simulated in one loop (step, run by a projectileKit.Runner the kit spawns on first use); what they look like is drawn from per-look pools of reused entities (projectileKit.render).

Nothing here is networked. A game that wants every peer to see a shot sends the shot's spec to the other peers and fires it there with logic = false (drawn, no onHit). turretsKit does exactly that for its turret fire.

local PK = require("projectileKit.api")
PK.fire({ kind = "bullet", from = muzzle, target = enemy, speed = 70, look = "tracer",
          onHit = function(shot, hit) HK.damage(hit.target, 8) end })
PK.fire({ kind = "shell", from = muzzle, to = spot, arc = 6, look = "shell", impact = "blast" })
PK.beam("laser1", from, to, "laserRed", 0.12)        -- every frame while it fires
PK.arc(from, to, { look = "arcCyan" })               -- one lightning bolt
PK.puff(pos, { look = "flame", vel = { 0, 0, 6 } })  -- one particle

Fields

  • VERSION: "1.1.0".
  • vec, motion, looks, render: the kit's sub-modules, re-exported.
  • BUDGETS: presets desktop, web, phone, each { maxShots, maxEffects, maxVisible, spawnPerFrame }.

Shots

  • fire(spec: any): any: fires one projectile and returns the shot table (shot.pos, shot.id). Spec fields:

    • kind: bullet | shell | missile (see projectileKit.motion)
    • from, to (aim point; defaults to the target's position), target (entity or id: bullets and missiles hit it on contact, missiles home on it)
    • speed (m/s), arc and gravity (shells), turnRate (deg/s, missiles), radius (contact distance), aimHeight (added to the target's position)
    • look, size, trail + trailEvery (puff look dropped behind it), impact + impactSize (burst look where it ends)
    • draw = false (not drawn), logic = false (drawn only, no onHit)
    • hitTest(shot, dt) (1.1.0): called after every step of a live shot (logic ~= false); return a target entity or id to end the shot as a "hit" on it (onHit's target), nil to keep flying. For bullets that may hit any of many targets.
  • kill(shot, reason?): boolean (1.1.0): ends a flying shot on its next step with reason ("expire" by default); its onHit runs with that reason. False when the shot is not flying.

    • onHit(shot, { pos, target, reason, aimedAt }): reason is hit, arrive or expire; target is set only on a hit
    • data: anything, kept on the shot

    Over the maxShots budget a shot lands at once instead of flying, so no hit is lost.

  • targetPos(target: any, height: number): Vec?: a target's position plus height, read once per target per frame (nil when it no longer exists).

Effects (cosmetic; over maxEffects the oldest gives way)

  • puff(pos, o?): a particle: look (default smoke), vel, life, size, grow, drag, rise, spin.
  • burst(pos, o?): expanding, fading sphere: look (default blast), size, life.
  • ring(pos, o?): flat ring widening to radius over life: look (a torus look, default shockRing), radius, life, hold (stay at full radius).
  • arc(from, to, o?): one lightning bolt: look (default arcCyan), life, segments (2..12), jag, width, seed.

Beams

  • beam(key: string, from, to, look: string?, width: number?, o: any?): draws or keeps drawing the beam named key. Call every frame while it is on; it fades out by itself o.hold seconds (default 0.12) after the last call. A white core is drawn inside unless o.core = false.
  • endBeam(key: string): stops a beam now.
  • hasBeam(key: string): boolean: whether that beam is drawn right now.

Loop, budget and readouts

  • step(dt: number): advances every shot, effect and beam (dt capped at 0.1) and draws them. The Runner calls it every frame in play; tests call it by hand.
  • ensureRunner(): spawns the Runner entity if it is missing (called by every fire/effect).
  • setBudget(t: any): sets maxShots, maxEffects, maxVisible, spawnPerFrame, or takes a preset name ("desktop", "web", "phone").
  • budget(): any: the budget in force.
  • suggestedBudget(): string: "phone" on a small screen, "web" in a browser, else "desktop".
  • stats(): any: shots, effects, beams, totals fired/hits/arrived/expired/instant, reused vs new shot tables, peaks, render pool stats and budget.
  • resetStats(): zeroes the counters.
  • prewarm(look: string, count: number): makes pool entities for a look ahead of time.
  • defineLook(name: string, spec: any, base: string?): any: adds or replaces a look.
  • lookNames(): { string }: every look name.
  • clear(alsoPools: boolean?): drops every shot, effect and beam (no onHit fires), and with true despawns the pooled entities too.