Boss Systems
Entity Behaviors
General-purpose entity behaviors provided by the framework (everything that is not a boss ability — those are in Combat, Defense and Utility abilities). Add them to the behaviors list of an entity type; unless noted otherwise, properties go directly on the behavior object.
"behaviors": [
{ "code": "nightonly", "fromHour": 20, "toHour": 6 },
{ "code": "lookatplayer", "range": 10 }
]The questgiver behavior has its own page: Quest Givers. Boss behaviors (boss*) are documented in Combat, Defense and Utility abilities.
Behavior codes with a : (such as alegacyvsquest:dialoguequests) must be written with the prefix exactly as shown.
alegacysummonedally
Server. Marks an entity as a summoned ally of a player (created by the summon-ally ability effect, which also writes the owner and expiry time into the entity). The ally crumbles to ash — no drops, no corpse — when its time runs out, its owner leaves, dies, changes dimension or gets farther than maxOwnerDistance. An ally loaded from a save without the owner/timer data (after a server restart) crumbles at once.
| Property | Type | Default | Description |
|---|---|---|---|
maxOwnerDistance | float | 48 | Distance from the owner beyond which the ally crumbles |
{ "code": "alegacysummonedally", "maxOwnerDistance": 48 }alegacyvsquest:dialoguequests
Server. Lets any conversable NPC (vanilla dialogue, NPCs made in the PlayerModelNpcs editor) drive quests from its dialogue without being a questgiver. It takes no properties; the NPC editor's "Quests" window stores the questgiver setup (quest list, always-quests, single-quest-at-a-time, max available, reputation NPC) for it.
Dialogue triggers (triggerData keys in brackets):
| Trigger | triggerData | Effect |
|---|---|---|
alegacyquest-accept | quest | Accepts the quest |
alegacyquest-complete | quest, force | Completes the quest |
alegacyquest-action | action, quest | Runs a quest action |
alegacyquest-journal | title, text, entry, quest | Adds a journal entry |
On every dialogue start it also refreshes the per-player dialogue variables player.queststage_<id> (1-based stage) and player.questcompletable_<id>, next to the existing questactive_ / questcompleted_ ones.
alegacyvsquest:npcplayermodel
Gives an NPC a player model (PlayerModelLib or another player-model mod): the behavior writes the model, size, skin, voice, outfit and held items into the entity so the skin behavior picks them up. Every key is read from the behavior first and falls back to the entity type attributes of the same name. A look pasted in the NPC editor wins over these values and survives reloads.
| Property | Type | Default | Description |
|---|---|---|---|
playerModel | string | — | Model code (e.g. seraph). Nothing else is applied without it |
playerModelSize | float | — | Entity size multiplier (used when > 0) |
playerModelSkin | object | — | Skin parts as { "partCode": "variant" } |
voiceType | string | — | Voice type |
voicePitch | string | — | Voice pitch |
outfit | object | — | Worn items by slot index "0".."18" → item code |
outfitByType | object | — | Same as outfit per entity code; keys are wildcard patterns ("*-t1"), first match wins |
rightHandItem | string | — | Item code held in the right hand |
leftHandItem | string | — | Item code held in the left hand |
{ "code": "alegacyvsquest:npcplayermodel", "playerModel": "seraph", "playerModelSize": 1.0,
"outfit": { "0": "game:clothes-foot-king", "3": "game:clothes-upperbody-king" } }alegacyvsquest:questdropondeath
Server. Drops items to the players credited for the kill (the players who damaged the entity — via the boss combat marker when present — or, failing that, the direct killer), with quest conditions. Items go to the player, not to the ground. Takes a drops array:
| Property | Type | Default | Description |
|---|---|---|---|
type | string | "item" | item, actionitem (a quest action item) or block |
code | string | — | Item or block code |
quantity | object | { "avg": 1 } | Amount distribution (avg, var, dist: uniform, gaussian/normal, invexp) |
onlyIfQuestActive | string | — | Drop only if the player has this quest active |
onlyOncePerQuest | bool | true | With onlyIfQuestActive: drop only once per quest instance (tracked in a quest variable) |
variableKey | string | drop_<code> | Name of the quest variable used for onlyOncePerQuest |
{ "code": "alegacyvsquest:questdropondeath", "drops": [
{ "type": "actionitem", "code": "mypack:sealed-letter", "onlyIfQuestActive": "mypack:find-letter" }
] }alegacyvsquestguionclick
Server. Right-clicking the entity opens a GUI for the player. guiType selects it; the only type that exists is serverinfo (the server info window) and any other value opens the same window.
| Property | Type | Default | Description |
|---|---|---|---|
guiType | string | "serverinfo" | GUI to open |
ambientmusicurl
Client. Plays an ambient URL music track while the local player is within range of the living entity and stops once they are farther than stopRange. The key is looked up in the client boss-music config; actual ducking is handled by the ambient music system.
| Property | Type | Default | Description |
|---|---|---|---|
musicKey | string | — | Track key from the client music config (nothing plays without it) |
range | float | 40 | Distance at which the music starts (min 1) |
stopRange | float | range * 1.1 | Distance at which it stops (never below range) |
catchable
Server. A player's hit catches the creature: it vanishes in a burst of sparks and the player receives currency. Hits by anything other than a player do nothing.
| Property | Type | Default | Description |
|---|---|---|---|
currency | string | — | Currency ID awarded |
pointsCurrency | string | — | Second currency awarded in the same amount |
messageLangKey | string | — | Lang key of the message sent to the player |
Entity type attributes read by it: wispValue (amount, default 1, minimum 1), catchSound (sound played on catch) and sparkColor ([r, g, b], default [200, 255, 220]).
{ "code": "catchable", "currency": "alegacyevents:wisps", "pointsCurrency": "alegacyevents:halloween-points", "messageLangKey": "alegacyevents:wisp-caught" }damagedummy
A training dummy: each hit by a player is reported to chat ([Dummy] <name> dealt X <type> damage, throttled to 4 per second, with the projectile name for ranged hits), knockback is removed and health is restored to full 50 ms later. Use it to test weapon damage.
encounterleash
Server. Leash and recall for mobs and bosses spawned by an Encounter. It has no JSON properties: the encounter runner writes the anchor, leashRange, out-of-combat range, return speed, check interval, damage grace (default 8 s), stop distance and stuck-teleport time into the entity when it spawns. A mob that leaves the leash range and has not been damaged for the grace period walks back to the anchor; a "no-kill recall" from the runner forces all mobs back at once. Taking damage cancels the return.
entitylight
The creature emits block light like a held torch.
{ "code": "entitylight", "lightHsv": [8, 6, 6] }lightHsv is [hue, saturation, brightness], each 0..31. If the behavior has no lightHsv, the entity type attribute lightHsv is used — handy with attributesByType for colour variants.
erraticdart
Server. Every few seconds the creature darts off in a random direction at a random speed, then returns to its AI. Meant for weightless flyers (wisps, gravityFactor 0); list it after taskai so the dart overrides the AI's motion. Optionally a dart starts a burst of several darts in new random directions.
| Property | Type | Default | Description |
|---|---|---|---|
pauseMinSec / pauseMaxSec | float | 3 / 8 | Pause between darts, in seconds |
dartMinSec / dartMaxSec | float | 0.5 / 1.8 | Duration of a dart, in seconds |
speedMin / speedMax | float | 0.03 / 0.12 | Dart speed (blocks per tick) |
maxVertical | float | 0.35 | Fraction of the speed that may go up or down |
minGroundGap | float | 0.6 | Minimum distance to keep from the ground (it never darts lower) |
burstChance | float | 0 | Chance (0–1) that a dart starts a series |
burstMin / burstMax | int | 2 / 3 | Number of darts in a series |
burstGapMinSec / burstGapMaxSec | float | 0.1 / 0.35 | Gap between darts in a series, in seconds |
{ "code": "erraticdart", "pauseMinSec": 3, "pauseMaxSec": 9, "dartMinSec": 0.4, "dartMaxSec": 1.6, "burstChance": 0.15 }explosivelocust
Server. A kamikaze creature: it leaps at players within leapTriggerRange and explodes fuseMs after it spawned or when it comes within about one block of a target, damaging players in explosionRadius. Can play a looping sound while it is alive. (Summoned by bosssummonritual it remembers the summoner for the damage scaling.)
| Property | Type | Default | Description |
|---|---|---|---|
fuseMs | int | 3000 | Time from spawn to the explosion |
explosionRadius | float | 3 | Blast radius |
explosionDamage | float | 8 | Blast damage (or a named level in explosionDamageLevel) |
damageTier | int | 3 | Damage tier of the blast |
damageType | string | "PiercingAttack" | Damage type |
leapTriggerRange | float | 12 | Distance at which it starts leaping |
leapCooldownSeconds | float | 1.0 | Pause between leaps |
leapHorizontalSpeed | float | 1.3 | Horizontal leap speed |
leapVerticalSpeed | float | 0.55 | Vertical leap speed |
loopSound | string | — | Looping sound |
loopSoundRange | float | 10 | Range of the loop sound |
loopSoundIntervalMs | int | 900 | Loop sound repeat interval |
loopSoundVolume | float | 0.6 | Loop sound volume |
explodeSound | string | "effect/smallexplosion" | Explosion sound |
explodeSoundRange | float | 18 | Explosion sound range |
explodeSoundVolume | float | 0.9 | Explosion sound volume |
{ "code": "explosivelocust", "fuseMs": 6000, "explosionRadius": 3, "explosionDamage": 9, "damageTier": 2, "damageType": "Poison" }invulnerablenpc
Makes a dialogue NPC immune to all damage and knockback — the protection questgiver applies, without any quest logic. For flavour NPCs (guides, audience) that should not flinch or move when hit. No properties.
killcurrency
Server. The player who kills this (non-boss) creature receives currency, read from the entity type attribute killCurrency:
"attributes": { "killCurrency": { "ashshards": 2, "runedust": 1 } }Keys are currency IDs, values are amounts (<= 0 is ignored). Only kills by a player count (including through a projectile). Bosses get currency through the boss kill credit instead — do not add both.
lookatplayer
Client only. The NPC turns its head toward the nearest player in range without moving its body (the model needs a head bone controller; it is attached automatically).
| Property | Default | Description |
|---|---|---|
range | 10 | Maximum distance to a player |
maxHeadYawDeg | 70 | Max horizontal head turn |
maxHeadPitchDeg | 25 | Max up/down head tilt |
smoothSpeed | 6 | Turn smoothing speed |
musicplayer
An NPC that plays a music track for nearby players (musician NPCs). The server sends the track and playback position; the client starts it as music and fades volume with distance to the entity. The track stops when the NPC despawns. Takes no properties; the NPC's hand slots are bound to its container inventory.
nightonly
Server. Outside the in-game hours fromHour..toHour (wraps midnight) the creature fades away in a puff of smoke. It never disappears while in combat, and a creature that still has a rider is left to its mount.
| Property | Default | Description |
|---|---|---|
fromHour | 20 | Hour the creature may exist from |
toHour | 6 | Hour it must be gone by |
A spawn rule with lifetimeHours can set a fixed despawn time instead of the hour window.
questtarget
Marks the entity as a target for killactiontarget objectives and keeps it on a leash.
| Property | Default | Description |
|---|---|---|
targetId | — | Target ID matched by the objective (target argument) |
maxHealth | — | Overrides the entity's max health on the server |
leashRange | 0 | Distance from the spawn anchor beyond which the entity walks back (0 = off) |
returnMoveSpeed | 0.04 | Walk speed while returning |
leashCheckMs | 1000 | How often the leash is checked |
While returning, an entity stuck for about 5 seconds is teleported to the anchor. Bosses that carry a combat marker also regenerate slowly after a pause in damage. Spawners can set the target ID and leash values per spawn (they override the JSON).
scarabhover
Server. Lets a scarab hover at a set height above the ground while it has a target. Only vertical motion is controlled; horizontal movement stays with the entity's AI. Encounters can widen maxTargetRange so the scarab keeps hovering toward players anywhere in the arena.
| Property | Type | Default | Description |
|---|---|---|---|
hoverHeight | float | 1.5 | Height above the ground to hold |
verticalSpeed | float | 0.08 | Vertical movement speed |
maxTargetRange | float | 24 | Range within which a player counts as a target |
groundScanRange | int | 16 | How far down it scans for the ground |
maxHeightAboveGround | float | 6 | Upper limit of the height above the ground |
descendToHeight | float | 3.5 | Height it descends to when there is no target |
{ "code": "scarabhover", "hoverHeight": 0.6, "verticalSpeed": 0.06, "maxTargetRange": 20 }scarableap
Server. The scarab launches itself at a nearby player and flies through the air for a short time before landing and resuming its AI.
| Property | Type | Default | Description |
|---|---|---|---|
cooldownMs | int | 6000 | Pause between leaps |
windupMs | int | 500 | Windup before the leap |
dashMs | int | 900 | Flight duration |
dashSpeed | float | 0.22 | Flight speed |
liftStrength | float | 0.18 | Upward push during the leap |
minRange / maxRange | float | 3 / 18 | Target distance window in which it may leap |
checkIntervalMs | int | 250 | How often it looks for a target |
sound | string | "game:sounds/creature/locust/hurt" | Sound played on the leap |
yAimFactor | float | 0.5 | How much of the height difference to the target it aims for |
yAimMax | float | 0.25 | Cap of the vertical aim |
{ "code": "scarableap", "cooldownMs": 6000, "windupMs": 600, "dashMs": 1200, "dashSpeed": 0.4, "liftStrength": 0.35, "minRange": 6, "maxRange": 30 }seasonalpresence
Server. The entity exists only while its seasonal event is active. Outside the event window it is stashed with its full state and put back at the same spot when the window opens again.
| Property | Default | Description |
|---|---|---|
eventId | — | Seasonal event ID (e.g. halloween) |
unique | false | Only one of this entity may exist; spawning it again replaces the previous one (event NPCs). Leave off for crowds such as wisps. |
shapeselectionbox
Both sides. Builds the entity's hit and selection volume from its model shape instead of a fixed box: the touch distance is taken from the shape's extent, the per-part selectionboxes picking gets its distance corrected to the player, and a yaw-aligned fallback box is used where attachment-point selection is not available (for example on the server before tesselation). Takes no properties; list it with the selectionboxes behavior for large multi-part creatures.
shiverdebug
Developer tool. Right-clicking the entity plays the next animation from a fixed list of shiver animations (hurt, run, walk, swipe, bite, die, idle, despair, headbang, mouth-*, stroke-*) and shows its name in chat. The animation is kept alive until the next click. Takes no properties.
spawnsrider / ridesentity
A mount-and-rider pair for bosses and NPCs without vanilla seats. Put spawnsrider on the mount and ridesentity on the rider (list ridesentity last so it runs after physics).
spawnsrider (mount, server):
| Property | Description |
|---|---|
riderCode | Entity code of the rider spawned together with the mount |
The mount remembers the last player who hit it so a dismounted rider knows whom to chase, and takes the rider along when it despawns without dying.
ridesentity (rider, both sides) — while the mount lives, the rider is pinned on its back, faces with it, plays a riding pose and (by default) passes every hit to the mount. When the mount dies, the rider dismounts and, if the mount was killed by a player, becomes aggressive toward that player. The link is the watched attribute alegacyvsquest:mountId, set by spawnsrider.
| Property | Default | Description |
|---|---|---|
seatHeight | 0.95 | Rider height above the mount's position |
rideAnimation | rideelk-idle | Pose animation while mounted |
passDamageToMount | true | Hits on the rider hurt the mount. With false the rider keeps its own health and hits on it provoke the mount. |
Entity type attribute passiveUntilProvoked (read by the boss ability gate): when true, the boss's abilities stay off until it is provoked; a mounted rider never counts as provoked.
// mount
{ "code": "spawnsrider", "riderCode": "mypack:bandit-rider" }
// rider
{ "code": "ridesentity", "seatHeight": 0.95, "rideAnimation": "rideelk-idle", "passDamageToMount": true }