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.

PropertyTypeDefaultDescription
maxOwnerDistancefloat48Distance 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):

TriggertriggerDataEffect
alegacyquest-acceptquestAccepts the quest
alegacyquest-completequest, forceCompletes the quest
alegacyquest-actionaction, questRuns a quest action
alegacyquest-journaltitle, text, entry, questAdds 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.

PropertyTypeDefaultDescription
playerModelstring—Model code (e.g. seraph). Nothing else is applied without it
playerModelSizefloat—Entity size multiplier (used when > 0)
playerModelSkinobject—Skin parts as { "partCode": "variant" }
voiceTypestring—Voice type
voicePitchstring—Voice pitch
outfitobject—Worn items by slot index "0".."18" → item code
outfitByTypeobject—Same as outfit per entity code; keys are wildcard patterns ("*-t1"), first match wins
rightHandItemstring—Item code held in the right hand
leftHandItemstring—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:

PropertyTypeDefaultDescription
typestring"item"item, actionitem (a quest action item) or block
codestring—Item or block code
quantityobject{ "avg": 1 }Amount distribution (avg, var, dist: uniform, gaussian/normal, invexp)
onlyIfQuestActivestring—Drop only if the player has this quest active
onlyOncePerQuestbooltrueWith onlyIfQuestActive: drop only once per quest instance (tracked in a quest variable)
variableKeystringdrop_<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.

PropertyTypeDefaultDescription
guiTypestring"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.

PropertyTypeDefaultDescription
musicKeystring—Track key from the client music config (nothing plays without it)
rangefloat40Distance at which the music starts (min 1)
stopRangefloatrange * 1.1Distance 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.

PropertyTypeDefaultDescription
currencystring—Currency ID awarded
pointsCurrencystring—Second currency awarded in the same amount
messageLangKeystring—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.

PropertyTypeDefaultDescription
pauseMinSec / pauseMaxSecfloat3 / 8Pause between darts, in seconds
dartMinSec / dartMaxSecfloat0.5 / 1.8Duration of a dart, in seconds
speedMin / speedMaxfloat0.03 / 0.12Dart speed (blocks per tick)
maxVerticalfloat0.35Fraction of the speed that may go up or down
minGroundGapfloat0.6Minimum distance to keep from the ground (it never darts lower)
burstChancefloat0Chance (0–1) that a dart starts a series
burstMin / burstMaxint2 / 3Number of darts in a series
burstGapMinSec / burstGapMaxSecfloat0.1 / 0.35Gap 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.)

PropertyTypeDefaultDescription
fuseMsint3000Time from spawn to the explosion
explosionRadiusfloat3Blast radius
explosionDamagefloat8Blast damage (or a named level in explosionDamageLevel)
damageTierint3Damage tier of the blast
damageTypestring"PiercingAttack"Damage type
leapTriggerRangefloat12Distance at which it starts leaping
leapCooldownSecondsfloat1.0Pause between leaps
leapHorizontalSpeedfloat1.3Horizontal leap speed
leapVerticalSpeedfloat0.55Vertical leap speed
loopSoundstring—Looping sound
loopSoundRangefloat10Range of the loop sound
loopSoundIntervalMsint900Loop sound repeat interval
loopSoundVolumefloat0.6Loop sound volume
explodeSoundstring"effect/smallexplosion"Explosion sound
explodeSoundRangefloat18Explosion sound range
explodeSoundVolumefloat0.9Explosion 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).

PropertyDefaultDescription
range10Maximum distance to a player
maxHeadYawDeg70Max horizontal head turn
maxHeadPitchDeg25Max up/down head tilt
smoothSpeed6Turn 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.

PropertyDefaultDescription
fromHour20Hour the creature may exist from
toHour6Hour 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.

PropertyDefaultDescription
targetId—Target ID matched by the objective (target argument)
maxHealth—Overrides the entity's max health on the server
leashRange0Distance from the spawn anchor beyond which the entity walks back (0 = off)
returnMoveSpeed0.04Walk speed while returning
leashCheckMs1000How 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.

PropertyTypeDefaultDescription
hoverHeightfloat1.5Height above the ground to hold
verticalSpeedfloat0.08Vertical movement speed
maxTargetRangefloat24Range within which a player counts as a target
groundScanRangeint16How far down it scans for the ground
maxHeightAboveGroundfloat6Upper limit of the height above the ground
descendToHeightfloat3.5Height 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.

PropertyTypeDefaultDescription
cooldownMsint6000Pause between leaps
windupMsint500Windup before the leap
dashMsint900Flight duration
dashSpeedfloat0.22Flight speed
liftStrengthfloat0.18Upward push during the leap
minRange / maxRangefloat3 / 18Target distance window in which it may leap
checkIntervalMsint250How often it looks for a target
soundstring"game:sounds/creature/locust/hurt"Sound played on the leap
yAimFactorfloat0.5How much of the height difference to the target it aims for
yAimMaxfloat0.25Cap 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.

PropertyDefaultDescription
eventId—Seasonal event ID (e.g. halloween)
uniquefalseOnly 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):

PropertyDescription
riderCodeEntity 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.

PropertyDefaultDescription
seatHeight0.95Rider height above the mount's position
rideAnimationrideelk-idlePose animation while mounted
passDamageToMounttrueHits 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 }

Press ESC to close