Log inGet started
World

Named Foes: Enemy Prefixes, Variants and Nameplates

README.md

prefixKit: named enemy variants: prefixes, behaviours and nameplates

Turn one enemy into many: "Burning Goblin", "Frozen Armoured Knight", "Watercolor Ink Goblin". A prefix changes how an enemy looks (tint, outline, size, an aura, an art medium) and how it behaves (stats, and small rules like regeneration, armour, dodging, shields, dash bursts, splitting or exploding on death), and the enemy gets a nameplate in one of eight styles. Works in any game with enemies: tower defense, action RPG, arena, roguelite. Multiplayer: behaviours run on the peer that owns the enemy; every peer draws the look and the nameplate from one synced component.

Version 1.0.4 (Prefix.VERSION).

1.0.4: the README and guides no longer use em dashes.

1.0.3: nameplates are rebuilt at updateHz (default 30) instead of every frame. Each rebuild re-lays out the plate screen, and with 40 plates that cost about 30 ms of UI layout a frame in a 130-enemy tower defense; capped at 24 plates and 30 Hz it was about 10 ms. updateHz = 0 restores the old every-frame rebuild.

1.0.2: nameplates now start drawing in play. Their frame driver was only started when the module loaded, which happens in edit mode in most games, so no plate was drawn once play began. Tracking an enemy now also starts the nameplate driver.

Install

zero zeromind installAsset <prefixKit package guid>

(search ZeroMind for prefixKit or "enemy prefixes nameplates"). It brings SecondWind (health, shields, damage filter; brings Lifeline and MatchFlow) and juiceKit (aura motes, explosions). It uses these when they are installed, and never needs them: spawnerKit (auto-apply on spawn, pooled enemies' speed and damage), creepsKit (chained damage filter, splitting through spawnFrom), turretsKit (frost slows respected unless slow-immune), mediumKit (art-medium looks; tint fallback otherwise).

Quick start

local Prefix = require("prefixKit.api")

-- on the peer that owns the enemy (the host for spawnerKit enemies):
Prefix.apply(goblin, { "burning", "giant" }, { baseName = "Goblin" })   --> "Giant Burning Goblin"

-- anywhere:
Prefix.nameOf({ "watercolor", "ink" }, "Goblin")         --> "Watercolor Ink Goblin"
Prefix.nameOf({ "watercolor", "ink" }, "Goblin", true)   --> "Watercolor Ink Goblins"
Prefix.stats({ health = 100, speed = 3 }, { "ink" })     --> health 140, speed 2.55, armor 3
Prefix.setNameplate("comicCaption")                       -- one setting, every plate

spawnerKit games: one line on every peer (it acts on the host only).

Prefix.autoApply()   -- kinds named "goblin__watercolor_ink" wear Watercolor + Ink, base name "Goblin"
-- or decide yourself:
Prefix.autoApply(function(enemy, kind) return { "burning" }, "Goblin" end)

No code: add the PrefixTags component to an enemy in a scene, set prefixes = "frozen,armoured" and baseName = "Knight"; the owner applies it when play starts.

The library (31 prefixes)

Names sort by group: rank, size, element, temper, medium (change with Prefix.setOrder).

idnamegroupwhat it does
eliteEliterankhealth x1.8, damage x1.4, bounty x2.5, +1 armour, gold outline, a bit bigger; makes it at least rare
championChampionrankhealth x1.5, bounty x2, holy aura: allies within 6 m get speed x1.15 and +2 armour
tinyTinysizescale 0.6, health x0.5, speed x1.25, damage x0.6, bounty x0.6
giantGiantsizescale 1.45, health x2.2, speed x0.8, damage x1.5, bounty x1.8
colossalColossalsizescale 1.9, health x4, speed x0.65, damage x2.2, +2 armour, bounty x3.5, slow immune
burningBurningelementfire tint and flame aura, damage x1.2, hits burn 6/s for 3 s
frozenFrozenelementice tint and frost aura, speed x0.85, health x1.2, +2 armour, slow immune, hits chill (35% slow, 2 s)
venomousVenomouselementpoison aura, health x1.1, hits poison 4/s for 5 s, regen 1%/s
shockingShockingelementspark aura, speed x1.1, dash x2 for 0.6 s every 3.5 s, reflects 20% as electric
swiftSwifttemperspeed x1.45, health x0.85
armouredArmouredtempersteel tint, health x1.2, speed x0.9, +5 armour
berserkBerserktemperdamage x1.3, below 50% health speed x1.7
vampiricVampirictempershadow aura, health x1.1, heals 50% of damage it deals and 10% of max when an ally dies within 6 m
regeneratingRegeneratingtemperhealth x1.1, regen 2%/s
ghostlyGhostlytemperpale, flickers out: untargetable and immune 1.4 s every 5 s, dodges 10%
explosiveExplosivetemperexplodes on death: 40 damage in 4 m
shieldedShieldedtempershield of 40% max health, recharges 8%/s after 3 s without a hit
splittingSplittingtemperhealth x0.9, splits into 2 copies (scale 0.65, health 0.4) on death
thornedThornedtemperreflects 30% of damage taken to the attacker
evasiveEvasivetemperspeed x1.1, dodges 25%
blessedBlessedtemperholy aura: allies within 5 m heal 2%/s
cursedCursedtempershadow aura, +3 armour, untargetable 1 s every 7 s
watercolorWatercolormediumlook: mediumKit watercolor; regen 3%/s
inkInkmediumlook: ink; +3 armour, health x1.4, speed x0.85
pencilPencilmediumlook: pencil; speed x1.3, health x0.75
toonToonmediumlook: toon; dodges 20%
animeAnimemediumlook: anime; dash x2.2 for 0.7 s every 3 s, health x0.9
comicComicmediumlook: comic; shield of 35% max health (no recharge)
paperPapermediumlook: paper; slow immune, speed x1.15, health x0.85
pixelPixelmediumlook: pixel; splits into 2 copies on death

Two or more medium prefixes make a hybrid: drawn with Medium.applyHybrid(entity, a, b, 0.5, { localOnly = true }) and the behaviours combine (Watercolor Ink = regen 3%/s + armour 3 + health x1.4 + speed x0.85). Without mediumKit the media draw as tints.

Add your own: Prefix.define("molten", { name = "Molten", group = "element", color = "#ff5a00", look = { tint = {1,0.4,0.1}, aura = "flames", scale = 1.1 }, stats = { health = 1.3 }, behaviours = { { id = "burn", dps = 8, duration = 2 } } }).

Stacking

health, speed, damage, bounty multiply; armor adds. The same behaviour from two prefixes merges into one: numbers add (regen 2% + 3% = 5%), dodge chances combine as 1-(1-a)(1-b) (capped at 75%), dash/phase periods take the shortest, multipliers the largest. Flat armour takes its amount off every hit but at least 15% always lands; poison and damage-over-time go around it.

Behaviours (15)

idparamsrule
regenpctheals pct of max health per second
armoramount, floorflat reduction per hit (floor share always lands)
dodgechanceignores a hit with that chance
shieldpct, regen, delaySecondWind shield of pct max health, recharging regen x max per second after delay
dashevery, duration, multspeed bursts
splitOnDeathcount, scale, healthcopies without the splitting prefix, via creepsKit.spawnFrom, spawnerKit, or Prefix.setSplitter(fn)
slowImmuneturretsKit slows and chill don't apply
explodeOnDeathradius, damageSecondWind explosion + juiceKit effect
enragebelow, multfaster below a health share
thornspct, typereflects damage to the attacker
vampiricpct, feed, radiuslife steal on hits, feeds on nearby ally deaths
auraradius, speed, armor, healbuffs nearby prefixed allies
phaseevery, durationuntargetable (SecondWind invulnerable) and flickering
burndps, duration, typeits hits set damage over time
chillslow, durationits hits slow (prefixed enemies directly; others: Prefix.onSlow + an ice hit)

New behaviour: Prefix.behaviour("magnet", { defaults = { radius = 5 }, tick = function(ctx, p, st, dt) ... end }). A ctx offers health, maxHealth, heal, shield, setShield, setSpeedFactor, setFlag, setUntargetable, position, damage, damageArea, dot, slow, allies, buff, spawnCopies, rand, now. Prefix hooks = { onSpawn(ctx, info), onTick(ctx, dt), onDamaged(ctx, amount, info) -> amount, onDeath(ctx) } run on the owner too.

Nameplates

One setting picks the style for every plate: Prefix.setNameplate(style); Prefix.nameplates() lists them.

stylelook
floatingclean bold label over the head, rarity coloured (default)
comicCaptionyellow comic caption box, heavy ink outline, hard shadow, speech tail
brushbrush-lettered ink calligraphy on a torn paper strip with a red seal; the health bar is a brush swash
pixelTag5x7 pixel font tag, dark box, crisp 1 px border, segmented bar
bannercrimson fantasy ribbon with gold trim and notched tails
neonglowing sci-fi mono lettering in a glass frame
minimalsmall plain text and a hairline bar
hiddennone

Rules (Prefix.setNameplateRule): always, elitesOnly (2+ prefixes or rare/unique), onHover, nearCursor, bosses (unique, elite, champion or colossal). Options (Prefix.setNameplateOptions): healthBar (health with a shield band), maxVisible (default 40), updateHz (how often the plates are rebuilt, default 30; 0 = every frame), scale, colorByRarity, scaleWithDistance (with refDistance, minScale, maxScale), declutter (overlapping plates stack upward, the rest are skipped), maxDistance. Rarity colours: normal #e8e8e8, magic #6f9cff, rare #ffd84a, unique #ff9636; rare and unique enemies also get a gold/orange outline. Plates stay readable from a top-down TD camera at 40 m (minimum scale 0.85).

API

Prefix.define(id, def) / Prefix.get(id) / Prefix.list(group?) / Prefix.groups()
Prefix.apply(entity, ids, { baseName, rarity?, health?, speed?, scale? }) -> name   -- owner
Prefix.clear(entity)                                                                 -- owner, restores stats
Prefix.of(entity) -> { prefixes, name, baseName, rarity, stats, state, phased } | nil  -- any peer
Prefix.nameOf(ids, baseName, plural?) / Prefix.plural(name) / Prefix.rarityOf(ids, explicit?) / Prefix.rarityColor(r)
Prefix.stats(baseStats, ids) / Prefix.behaviours(ids) / Prefix.describe(ids)        -- pure
Prefix.setOrder(groups) / Prefix.setMaxShown(n) / Prefix.parseKind("goblin__watercolor_ink")
Prefix.setNameplate(style) / Prefix.nameplates() / Prefix.setNameplateRule(rule) / Prefix.setNameplateOptions(o)
Prefix.setLookOptions({ tint, outline, rarityOutline, auras, motes, maxMotes, medium, scale })
Prefix.onApplied(fn(entity, info)) / Prefix.onSpeed(fn) / Prefix.onSlow(fn) / Prefix.behaviour(id, impl)
Prefix.autoApply(fn?) / Prefix.setSplitter(fn) / Prefix.useSpeed({ get, set }) / Prefix.speedMultiplier(e) / Prefix.isTargetable(e)
Prefix.useSecondWind(module?) / Prefix.useMedium(module?) / Prefix.damageFilter / Prefix.debugStats() / Prefix.VERSION

Component prefixKit.PrefixTags (synced): prefixes (comma list), baseName, rarity, scale, state (1 phased, 2 shielded, 4 enraged, 8 dashing, 16 slow immune, 32 dodged), seq, applied, showPlate.

Multiplayer

  • apply/clear/autoApply act on the owner of the enemy (the host for spawnerKit). Stats go through SecondWind (synced health) and spawnerKit's synced Enemy fields.
  • The owner writes PrefixTags; every peer reads it and draws tint, outline, size, aura and art medium locally (localOnly), and its own nameplates. The only per-frame traffic is SecondWind's health; behaviour state travels as one small state number when it changes.
  • Prefix.of works on every peer; Prefix.speedMultiplier/isTargetable answer on the owner.

Performance (measured in the gallery, native engine)

  • Owner: the behaviour tick runs 10 times a second over all prefixed enemies; see the KIT notes for the 150-enemy profile.
  • Nameplates: one screen, one projection per enemy per frame, at most maxVisible plates, plate content cached until name/style/rarity/health bucket/size bucket changes.
  • Looks: built once per enemy (and again only when its look's parts are rebuilt), aura rings are one model each, juiceKit motes for at most 10 enemies on screen every 0.3 s.

Known limits

  • Health, shields, armour, dodge, phase and the damage chain need SecondWind; without it prefixes still name and draw, and stats apply only through Prefix.useSpeed.
  • damage scales spawnerKit's Enemy damage; other games read Prefix.of(e).stats.damage. bounty is a number your economy reads (Prefix.of(e).stats.bounty).
  • SecondWind has one damage filter: prefixKit installs into creepsKit's chain when creepsKit is registered, else directly. A game that sets its own SecondWind filter should call Prefix.damageFilter(vitals, amount, info) inside it.
  • turretsKit slows are re-applied over prefix speed changes at 10 Hz; a slowed enemy that starts a dash keeps the slow.
  • Size scales the look's child parts, not the root, so spawn effects keep working; colliders are not resized.
  • Phase makes an enemy immune (SecondWind invulnerable); towers may still aim at it.
  • mediumKit is optional and found as mediumKit.api; until it is installed the media draw as tints.

Files

api.module (the API), library.module (prefixes), naming.module, stats.module, behaviours.module, brain.module, runtime.module (owner), visuals.module and nameplates.module (every peer), dummy.module (a health model for tests and design), PrefixTags.component, prefixKit.testSuite (31 tests), two guides.