Log inGet started
Package

api.module

README.md

turretsKit.api

The one interface to turretsKit. Turrets are turretsKit.Turret components on synced entities. The peer in charge of a turret (see turretsKit.net) picks its targets, fires and deals damage; every other peer follows the synced target and draws the same shots. Every setter works from any peer: on a peer not in charge it is sent to the one that is.

local TK = require("turretsKit.api")
TK.addTurret(entity.spawnSynced("Gun", { position = { 0, 0, 5 } }), { def = "machineGun", targeting = "first" })
TK.setDef(gun, "tesla")            -- swap what it is (its def), live
TK.setTargeting(gun, "strongest")  -- swap how it picks, live
TK.upgrade(gun)                    -- next tier (asks your economy hook)
TK.sell(gun)                       -- removes it, `sold` event carries the value
TK.info(gun)                       -- every number, read back

A turret argument (t) may be an entity, an entity id or the component.

Fields

  • VERSION ("1.0.0"), TURRET (the Turret component asset), EVENTS.
  • Sub-modules: catalog, targeting, aim, targets, combat, net, looks, projectiles (projectileKit.api).
  • Pass-throughs: define, defineStyle (catalog), defineTargeting (targeting), addTarget, removeTarget, setProgress (targets), speedMultiplier, onSpeed (combat).

Placing and changing turrets

  • addTurret(e: any, opts: any?): any: puts a Turret on an entity (use entity.spawnSynced) or updates the one it has. opts = any Turret fields; walls (and withHealth = true) also get SecondWind health. Returns the component.
  • place(pos: any, typeId: string, opts: any?, by: any?): (any, string?): builds a new turret at runtime, paying the build cost; extra opts yaw (degrees) and name.
  • set(t, field: string, value: any, by: any?): (boolean, string?): changes def, targeting, tier, style, team, active or targetPlayers (validated).
  • setDef(t, typeId), setTargeting(t, mode), setTier(t, tier) (no money), setTurretStyle(t, styleId): shorthands for set.
  • cycle(t, field: string, dir: number?): any: steps def, targeting, tier or style to the next (1) or previous (-1) value; returns it.
  • setStyle(styleId: string) / defaultStyle(): string: the world default for turrets whose style is "auto", on this peer (call it where every peer runs, e.g. a scene entrypoint).
  • setStyleAll(styleId: string): writes every turret's own synced style.
  • styleOf(t): string: the style a turret actually draws with.

Money

  • setEconomy(hooks: any?): { spend = fn(cost, info) -> boolean, refund = fn(amount, info) }, info = { turret, def, tier, by, reason = "build" | "upgrade" | "sell" }. Without hooks, building and upgrading are free and selling refunds nothing.
  • upgrade(t, by: any?): (boolean, string?): next tier; reasons "max", "money", "sent".
  • sellValue(t): number: what selling gives back now.
  • sell(t, by: any?): (number, string?): refunds, fires sold, despawns the turret.

Reading back

  • info(t): any: { id, def, label, description, tags, role, delivery, damageType, targeting, tier, tierName, maxTier, style, state, target, kills, stats, base, boost, special, specialLabel, specialValue, costs, limits, aim, owner }.
  • stats(t): any: the resolved numbers with support boosts (see catalog.stats).
  • types(): { any }: every turret type with its tiers, costs and stats.
  • styles(): { any }: { id, label, description } per style.
  • modes(): { any }: { id, label } per targeting mode.
  • all(): { [string]: any } / runtime(t): any: turret runtimes on this peer (comp, stats, type, focus, ...).
  • idOf(x): string?, componentOf(x): any: resolve a turret argument.
  • boostFor(t): any: { fireRate, damage, range, from } from same-team support beacons in reach (strongest counts, no stacking).
  • report(): any: turrets, how many this peer is in charge of, projectile, combat and net stats, default style.

Events

  • on(event: string, fn: (any) -> ()): any: listen to built, upgraded, sold, changed, fired, kill, targetChanged, or "*". payload.event names it; payload.local is true on the peer that made it happen. Money events reach every peer, so act on them where payload.local is true. Returns { Disconnect }.

Budget and frame

  • setBudget(b: any): projectile budget preset ("desktop", "web", "phone") or numbers; otherwise the kit picks projectileKit's suggested preset on first use.
  • _frame(dt): once-a-frame shared work (combat tick, cloud visuals, net flush), called by every Turret; extra calls in a frame do nothing. _register, _unregister, _emit, _ensureHealth, _cloudVisual are internal to the kit.