Bastion Works: Towers, Turrets and Targeting Kit
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: presetsdesktop,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(seeprojectileKit.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),arcandgravity(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, noonHit)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'starget), 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 withreason("expire"by default); its onHit runs with that reason. False when the shot is not flying.onHit(shot, { pos, target, reason, aimedAt }):reasonishit,arriveorexpire;targetis set only on ahitdata: anything, kept on the shot
Over the
maxShotsbudget a shot lands at once instead of flying, so no hit is lost. -
targetPos(target: any, height: number): Vec?: a target's position plusheight, read once per target per frame (nilwhen it no longer exists).
Effects (cosmetic; over maxEffects the oldest gives way)
puff(pos, o?): a particle:look(defaultsmoke),vel,life,size,grow,drag,rise,spin.burst(pos, o?): expanding, fading sphere:look(defaultblast),size,life.ring(pos, o?): flat ring widening toradiusoverlife:look(a torus look, defaultshockRing),radius,life,hold(stay at full radius).arc(from, to, o?): one lightning bolt:look(defaultarcCyan),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 namedkey. Call every frame while it is on; it fades out by itselfo.holdseconds (default 0.12) after the last call. A white core is drawn inside unlesso.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): setsmaxShots,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,renderpool stats andbudget.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 (noonHitfires), and withtruedespawns the pooled entities too.