Improving the XML Documentation


As some of you probably noticed the Public Documentation is not complete and at times is a bit confusing, the goal of this thread is to create a list of things that needs to be updated as well as help clarify/fix errors while waiting for the official documentation to be updated.

If you find anything that’s not on this list feel free to comment it so I can add it!
I’ll also keep a temporary documentation here while waiting for the official documentation to be updated.

#Public Documentation

List of errors/pages that need clarification

  • Condition Effects list is missing several status effects and is wrong/does not explain how Pet Stasis works.
  • Transition List is missing some transitions.
  • PlaySound behavior page uses PlaceMap params, it also doesn’t explain how to define sounds.
  • Embed page does not give any information about Params.
  • Tag page does not give any information about Global Tags.
  • ConditionEffectAura behavior page missing ignoreInvisible param.
  • CopyDamageRecord behavior page does not explain <KeepDamageRecord/>.
  • GrenadeToss behavior page is missing color param.
  • ObjectToss behavior page is missing textureSourceId and color params.
  • TrapTrigger behavior page has incorrect param name for conditionEffect and conditionDuration, should be condEffect and condDuration respectively, cooldownJitter is also not formatted correctly.
  • Shoot behavior page is missing information on defaultAngle with forward.
  • Missing enemy projectile properties <FaceDir/> and <NoRotation/>, need explanation of <Magnitude> for <Parametric>.
  • Projectile page need more information on <Rotation> and <AngleCorrection>.
  • Missing SetTag, ClearTag, SetGlobalTag, ClearGlobalTag, RestoresBreath, RemoveOnEmpty, RemainVisible, OryxTaunt, Taunt and VictoryAtDeath behaviors.


  • Add a list of all object ids as they might be required for some behaviors.
  • Add a list of all possible XML Tags as well as an explanation for each of them.
  • Add a list of all possible terrains as well as their altitude number.
  • Add a tips and trick section.
  • Add gifs to illustrate behaviors.

#Temporary Documentation

This only contains information that is either wrong on the Public Documentation or not available there!

Condition Effects

Players only:

  • Darkness: Visibility decreases to a small area around the player and prevents enemies from displaying red dots on the minimap. All entities outside of the area are completely invisible.
  • Unstable: A character shoots in random directions when attacking. Also applies to abilities that require aiming (spells, poisons, etc).
  • Silenced: Prevents player from using their ability. Unlike Quiet, Silenced does not deplete the player’s MP.
  • Pet Stasis: See pet only effects.

Players and enemies:

Note: While those effects technically work on both players and enemies, the result might differ slightly between the two.

  • Nothing: Does nothing. (Mostly used as a default value.)
  • Petrify: Can not move or attack, but can still take damage.
  • Curse: Take 20% more damage.
  • Armor Broken Immune: Immunity to Armor Break.
  • Stun Immune: Immunity to Stun.
  • Slowed Immune: Immunity to Slowed.
  • Dazed Immune: Immunity to Dazed.
  • Curse Immune: Immunity to Curse.
  • Petrify Immune: Immunity to Petrify.

Pets only:

Effects on Pets currently only work on Projectile by adding target="1" to the <ConditionEffect> tag.

Stasis: Player’s pet is unable to cast for the duration of the effect.

List of Transitions
  • playerWithin: A player is within the specified number of squares. This includes invisible players. (distance|number of players)
  • noPlayerWithin: There is no player within the specified number of squares. This does not include invisible players.
  • exist: There are objects of the specified type in this dungeon. (objectId|amount)
  • hasGlobalTag: Transition if this global tag is set.
  • noGlobalTag: Transition if this global tag is not set.
  • hasConditionEffect: Transition if the creature is inflicted by that condition effect.


One of the great things about Embeds are params!
Params allow you to replace a value in your Embed with another without having to rewrite it!
This is quite useful for somewhat complex patterns where there is only minor differences between 2 use.


First, let’s define our Embed

<DefineEmbed name="Shotgun">
  <Behavior numShots="{numShots}" projectileId="0" angle="{angle}" cooldown="1">Shoot</Behavior>

Next, let’s make a shotgun of 7 shots with an angle of 25, and another of 12 shots with an angle of 15.

<Embed name="Shotgun"><Param name="numShots">7</Param><Param name="angle">25</Param></Embed>
<Embed name="Shotgun"><Param name="numShots">12</Param><Param name="angle">15</Param></Embed>

Ta-da! Our monster now is absolutely unfair, but you now know how to use embeds to their full potential! It might not look like much, but on more complex behaviors it’s incredibly useful and allows you to cut down the amount of line (and work!) by quite a lot!

Tip: Keeping your Embed + Params on one line is useful if you are working with a pattern since every number you need to change will be in a clear column, however in some other situations, indenting it might be a better idea, it’s all up to you.


Global Tags

Global Tags are tags that are stored on the map instead of on a monster, this means all monster in the same map can detect it.
It uses its own set of behavior/transition so make sure you use the right one!


To define a sound, simply add a <Sound id="x">sound/path</Sound> tag to your monster.

  • soundId (int, default 0): specifies the sound


  • ignoreInvisible (boolean, default false): whether to ignore invisible objects

Need a <KeepDamageRecord/> tag on Monster you want to copy the damage record from.


  • color (uint, default 0xFF0000): color of throw effect particles


  • textureSourceId (string, default empty): object id of which the texture is used for the throw effect (will overwrite particles)
  • color (uint, default 0xFFC600): color of throw effect particles


  • condEffect (string, default Nothing): name of condition effect
  • condDuration (float, default 5.0): duration of effect


  • defaultAngle:
    • forward (float, default 0): added to the movement direction (30 aims 30 degrees right of the object’s direction, -20 aims 20 degrees left of the object’s direction)


Set a tag

  • tagName (string, default empty): name of tag to set


Clear a tag

  • tagName (string, default empty): name of tag to clear


Set a global tag

  • tagName (string, default empty): name of global tag to set
  • sendNotification (boolean, default false): sends to all players (used for Davy keys)
  • notificationCooldown (float, default 3.0): to reduce traffic
  • notificationType (int, default 0): notification type


Clear a global tag

  • tagName (string, default empty): name of global tag to clear


Restores breath (Used for Ocean Trench Vents)

  • radius (float, default 1.0): restore range
  • speed (float, default 50.0): restore speed


Removes once empty (Used for Containers)


Will always be rendered by the client, can be used to have monsters still shoot for players even when far away


Used for encounters (requires taunts in separate file)


Send messages to annoy players (requires taunts in separate file)

  • listId (string, default self): name of monster to look up taunts for
  • broadcast (boolean, default false): whether to yell or just chat


Special Behavior for Oryx only, drops Locked Wine Cellar Portal when it’s Oryx the Mad God 1, otherwise Portal to Nexus

Xolotl the Lightning God

now that I’ve finally gotten around to seriously reading this and working with it, I’ve got some additional feedback to go here along with some of the other stuff you’ve mentioned. my list is nowhere near as comprehensive as yours because I can’t know what’s missing in the first place, but here’s what I think needs fixing (including nitty-gritty typos):

typos and other visual oddities:

errors and unclear material:

additional questions:

  • how do you create enemy AoE blasts like those used in the Parasite Chambers? TrapTrigger only works against enemies.

  • how do you make AoE explosions that can affect both monsters and players? currently only the Parasite Chambers’ bomb barrels are the only things to do so.

  • I know when players hear “stacked shots” they think of brutally unfair instakill attacks, but is there a way to force two projectiles to go off at exactly the same time anyway? the Stone Caves of Nores 2 uses stacked shot pairs for aesthetic purposes (the second shot involved does nothing).

That’s all I can think of for now, although I think I’m forgetting something. I know I’m asking a ton of questions, but I’d like some answers anyway. hopefully this can make the documentation more non-tester friendly.

I’d also suggest the documentation be broken down into 3 sections: a tutorial of the absolute basics (basically the tutorial that’s already there), an advanced tutorial walking you through a much more complex boss enemy (putting all or almost all pieces shown together on a single enemy, currently not included), and a comprehensive list of all XML tags and what they do (sort of there, but doesn’t come close to including everything). hopefully splitting it into a basic tutorial, an advanced tutorial, and a comprehensive index will make things more clear. I know having a complete list of absolutely everything would help me trying to find help on a very specific thing.

The Stone Caves of Nores 2: a Dungeon by Xaklor

Lots of great questions, I’ll try to answer most of them but I don’t know the exact answer to each of them and I’d need to get back to you later after I’ve experimented with it some more.

  • <XPMult> is technically correct for that specific example, for a more broad explanation it would need an additional line stating that the base XP of a monster can not exceed 195.

  • Speed in general would need a separate page for it as player speed, projectile speed and behavior speed all use different units.
    For reference:
    Player: tps = 4 + 5.6 * (SPD / 75)
    Projectile: tps = Speed / 10
    Behavior: tps = Speed * 5

  • <Texture> is for what we call “object sheets” where every sprite is independent of each other, <AnimatedTexture> is for what we call “character sheets” where sprites are grouped in 5 frames, 1 idle 2 moving and 2 attacking.

  • Projectile Ids as far as I know are only ever numbers in the game, so I’d have to check and see if you can actually put anything there or not. (Most likely not.)

  • Regarding buckets, what makes a behavior fail is currently not documented which is why you don’t really have that information here.
    You can use any term for the bucket and as far as I know it groups everything together, buckets are not state specific as well. You can have only 1 bucket per behavior, but use an unlimited amount of bucket throughout the monster.

  • Projectile types needing to be less than 0xFF is information from a long time ago, ignore it.

  • Embeds are definited on the monster itself and can be nested (For example Void Entity’s attacks and center attacks are two different embeds that are used into its moving behavior which is also an embed.) however that has some limit which means you can’t change params from the top Embed and thus limits what you can do with nested embed, it’s mostly useful to not have to copy the same lines 50 times.
    Currently embeds are local and can’t be used by anything else than the monster it’s defined for.

  • I’m pretty sure starting point is the center of the BackAndForth, but i’d need to look into it some more.

  • Have barely used Buzz so I’ll need to get back to you later.

  • ChangeGround only changes one tile yes, Void Entity uses PlaceMap and it’s what you’d want to use for anything other than a 1 tile change.

  • ConditionEffectAura is how Marble Pillar, Sewers Liquid (DS Sick) etc… works, it gives a condition effect to everyone around it. Negative value is already on the doc but isn’t explained greatly, it makes it so the effect never wears off (Lab’s green liquid uses it).

  • ClearConditionEffectAura simply removes status effect to people around it, the blue liquid in Lab uses it.

  • Damage Record is undocumented, so I’ll get back to you later.

  • Explode cannot use two projectiles at once, for an example on how to do that, here’s how the Marble Colossus does it:

	<State id="Explode">
		<Behavior effect="Invulnerable">ConditionEffect</Behavior>
		<State id="Wait">
			<Transition afterTime=".8">Shoot</Transition>
		<State id="Shoot">
			<Behavior projectileId="17" numShots="45" angle="8" type="auto">Shoot</Behavior>
			<Behavior projectileId="18" numShots="30" angle="12" type="auto" defaultAngle="9">Shoot</Behavior>
		<Behavior projectileId="16" numShots="45" initialDelay="1" range="0" dropLoot="true" giveXP="true">Explode</Behavior>
  • Need to test it, but I believe -1 does make the monster follow indefinitely, you can achieve that behavior by having the cooldown at 0 anyway so it’s not really a big deal.

  • Need to test negative heal on HealZap.

  • Yes MMAD won’t be triggered if an enemy dies outside of the state the behavior is located in.

  • Add textureSourceId=“Monster Id Here” to the ObjectToss behavior.

  • .jms are made using an editor that isn’t currently available to the public (although you have probably seen it/versions based on it that aren’t official).

  • Never really used ReleasesSpawnAtDeath, but I assume that yes.

  • Need to test Shadow.

  • flashRepeats at 0.0 will simply not have the flash repeats, what you can do is have the flashRepeats be increadibly high (like 10000 for example), it will infinitely repeat then. That method does have 1 issue, it will continue on even on state transition, but there’s an easy fix to it: simply have another ShowEffect behavior with a flashPeriod and flashRepeats of 0.

  • Have not used Swirl a lot, but if you look at the params between the two behaviors you’ll notice they don’t offer the same possibilities. As for other enemies, don’t have access to the entire xml, so sadly can’t answer that one.

  • Undocumented behavior called AreaOfEffect is what PChambers uses for the AoE. (It’s quite similar to the GrenadeToss behavior in terms of params)

  • PChambers barrels actually use both AreaOfEffect and TrapTrigger at once!

  • Simply having the Shoot behavior twice but with a different projectile Id should do the trick.

Hopefully this cleared up some things, I’ll try and experiment on the few things I couldn’t answer, but can’t promise I’ll have the time to do it. If you have some more questions, keep them coming I’ll try my best!


still looking forward to some of those answers, my ability to complete my dungeon xml depends on some of those. until then, here’s some more questions:

did you mean 1 bucket per state? or can I only have one bucketed <Behavior>Shoot</Behavior> on the whole monster?

  • what happens if you use a puri or holy water while still inside a ConditionEffectAura?

  • can you have two “moving” Behaviors at the same time? for example, if you use Move and BackAndForth at the same time will the enemy zigzag in that direction?

  • at what point is the turnRate for BackAndForth applied? at each “point” where it flips direction, or over time while moving? if it is while moving, does that make it do this weird bendy wander movement or go back and forth over an arc?

  • so does AreaOfEffect look like: <Behavior radius="5.0" damage="120" color="0x00FF00">AreaOfEffect</Behavior>

  • is Guill’s “jump” function simply Guill ObjectToss-ing a “new” Guill and then immediately despawning, or is there an actual “jump” behavior? if the jump is an ObjectToss, is there some way to keep track of damage dealt to a jumping enemy to prevent it from respawning at full health after each jump?

  • is there some way for enemies to rewrite their own information? for example (and what I really care about): can an enemy change the <Z> tag at will somehow or is it constant?

  • can you give a more specific rundown of what “facing” is and what uses it?

  • is there a way to restrict a enemy movement to a specific kind of tile? can I use that to make a “string” of tiles that moves the enemy along?

I’m sure I’m still forgetting something, but that’s what I’ve got for now. also, here’s a few enemies I’ve finished using what I can understand. is there anything wrong with these? ignore the “FIXME’s”, they’ll be filled in later.

<Object id="Blaster Artifact 1" type="FIXME">
	<Enemy />
	<Projectile id="0">
		<ObjectId>Nores Bit</ObjectId>
	<State id="Offset1">
		<Behavior numShots="5" angle="20" defaultAngle="5">Shoot</Behavior>
		<Transition afterTime="0.4">Offset2</Transition>
	<State id="Offset2">
		<Behavior numShots="5" angle="20" defaultAngle="-5">Shoot</Behavior>
		<Transition afterTime="0.4">Offset2</Transition>
	<Behavior bucket="movement" range="0.6" speed="0.4">Follow</Behavior>
	<Behavior bucket="movement">Wander</Behavior>
	<Behavior time="5.0">Decay</Behavior>

Blaster Artifact 1 should move slowly toward players if they are within 10 tiles at 2 TPS, and wanders around if they aren’t within 10 tiles. after 5 seconds, it should despawn. it fires shotguns of 5 Nores Bits at players every 0.4s, and fires these at alternating angles aimed slightly to the left and then right.

<Object id="Nores Bomb" type="FIXME">
		<Enemy />
		<StasisImmune />
		<StunImmune />
		<Projectile id="0">
			<ObjectId>Nores Star</ObjectId>
			<MultiHit />
		<Behavior effect="Invulnerable">ConditionEffect</Behavior>
		<State id="Waiting">
			<Transition afterTime="1.5">Exploding</Transition>
		<State id="Exploding">
			<Behavior flashPeriod="0.5" flashRepeats="50">ShowEffect</Behavior>
			<Behavior initialDelay="1.0" range="0.0" numShots="36">Explode</Behavior>

Nores Bombs simply stand still, flash twice, and then explode. the total lifetime of the Nores Bombs should be 2.5s, and the flashes should appear after 1.5s have passed

super simple behaviors, but I want to be sure I’m getting the simple stuff right before I move on to the more complex enemies and bosses.


I’ll help answer some of these.

Each behavior can only be part of a single bucket. You can have many buckets throughout each state and can have multiple versions of any behavior (so, if you had 2 Shoot behaviors, they can be in the same bucket).

If the ConditionEffectAura is still going on, the status effect will be reapplied.


I actually can’t answer this one. Sorry :c

Yep. It’s pretty much exactly like GrenadeToss.

I think so, but it’s possible to do it with some XML wizardry: make the original entity go invisible, ObjectToss a fake entity with the same texture that Decays on spawn toward the final location, and have the original entity move to the final location.

I’m pretty sure it’s a constant, but I could be wrong.

I don’t know much about this, either. Sorry.

Using some buckets and crazy XML, you should be able to do it by having invisible entities spawn over those tiles, having the enemy Protect those entities, while also having the enemy chase players.

These both look pretty good to me. Keep it up!


daaaang, I don’t know if I can pull this stuff off without some sort of visual feedback from a testing server but I’ll give it a shot at least.


is it reapplied instantly as if it was never gone, or is there a teeny tiny gap where the effect is gone? for example: if I had an enemy with a paralyze aura and a player caught inside used a puri, would they remain stationary or inch forward slightly?


I haven’t tried this myself, but hypothetically, there should be a small gap. It shouldn’t be long enough for a player to make it out unless they’re right on the edge of the Aura, though.


new batch of questions for the documentation:

  • how do you make an enemy invisible? tons of stuff does this already, yet I was surprised to find that there is no mention of invisibility either in the official documentation nor in your own “Temporary Documentation”.

  • what does childId work with the Shoot behavior? how is it different from the MakeMinions behavior? what do the other fields on Shoot do when you give it a childId (like angle)?

  • is the paralysis immunity condition effect Paralyze Immune or Paralyzed Immune?

  • can you add a random element to some fields? for example, I’m guessing Oryx uses a minor subphase that uses a bunch of random transitions to control which phases he goes into, but can you make a Shoot behavior with a random defaultAngle?

  • is there a way to make an enemy back up away from a player without using KeepDistance? that also makes them move toward players if they’re too far away, but what if I wanted to only make them back up? I’m almost certain at least one enemy has this behavior in-game already but I forget which

still waiting for answers on the older questions you guys couldn’t answer, Buzz in particular is something I will almost definitely have to use, but I need more information on it. also a double-check on BackAndForth would be helpful.


Add this after your <Texture>:

<AltTexture id="1">

And change its texture to this one using <Behavior altTextureId="1">SetAltTexture</Behavior>. When you transition out of the state, it reverts to the original Texture/AnimatedTexture.

I’m not sure on this one, but I think childId basically changes Shoot into MakeMinions, but affected by Stun. The other fields shouldn’t do anything at all.

Paralyzed Immune

You can’t do this directly, but if you use embeds and a bunch of different states with different embed values, then have a state be randomly chosen, it should work to the same effect.

Just use KeepDistance with and absurdly high distance.

EDIT: If you mean make it go to a certain distance, then stop moving, you could probably make it use KeepDistance with distance being super high, then transition to a second state where it doesn’t move it all once it reaches your desired distance, and have it transition back when a player is closer than that distance.


No new questions, just putting up answers you guys have given me in Discord for future reference and for others. Discord has the advantage of getting information faster, but it disappears under new messages after time.

.gif used above

I would like to hear back about the stuff I asked about above at some point (Shadow, HealZap, Damage Record, etc.), but most importantly for me would probably be Buzz. so if you only have time to test one or two I’d like to know about that one, especially how far past a player Buzz takes them or how long each Buzz lasts.


You know, I have to give you tons of credit for working on XML without even being able to test it. That’s incredibly dedicated! Imo, Deca should bring you into UGC immediately.


honestly, if given the ability to test and run my own xml I might spend a couple days just throwing whatever at it just to see what happens and what minor quirks each tag has. I’m the kind of person who wants to know everything, not just what people tell me is useful.


That’s kind of what I did when I started. Even now, I’m still screwing around and trying to figure out cool stuff with XML.


I’m fairly certain this could be accomplished with a Follow whose distance to follow to is higher than or equal to the activation range. This should only make them flee up to the activation range.


I thought of making a seperate thread, but @Xaklor’s stuff made me reconsider.
These are more questions out of curiosity and will probably never see the light of day, but anyway:

  • Is it possible to, besides bullets, also modify the relative position of an AreaOfEffect attack?
  • Is it possible to combine a GrenadeToss behaviour and a normal Shoot behaviour with a delay to effectively create a grenade that “explodes” into multiple bullets?

The last question I have is more loot-based, but I have no other place I can think of where to ask this.

  • Is it possible to have two 100% chances chained to a threshold, and have them then be randomly chosen between? To be more precise: dealing 70% of an enemy’s HP in damage gives the attacker a 50% chance of getting exclusively item A and a 50% chance of getting exclusively item B, and thus a 0% chance of getting both or neither.


No, as of now that behavior can only originate from the object causing it.

I’m not entirely sure I understand the question, but I believe the answer is no. However, you could use ObjectToss to create an invisible entity which then immediately releases whatever projectiles you want, which would ultimately achieve the same effect.

No, once you’ve passed a threshold, there’s no way to revoke that qualification due to a player reaching a higher threshold.


I meant the two chances being chained to the same threshold.
To be a bit more specific: an enemy with 1000 HP that has a threshold of 900 HP. Once a player hits that threshold, that player then has a 50% chance of getting an attack potion and a 50% chance at getting a dexterity potion. The player cannot get nothing nor can they get both an attack and a dexterity potion.
Is that possible, or will this reciprocate the same main answer? (aka no lmao seel y’all’s wild)


No, there’s no way to do that at the current time. The drops would need to be listed separately, which means that the player would qualify for both rather than creating an either/or situation.


you could however, have the enemy spawn invisible entities that move into position and then those entities use AreaOfEffect. if it’s for a complex boss battle you could also just have them start in the room so they don’t have to move into position or anything, which would be easier.

I’ve quickly come to the realization that sometimes you have to think outside the box when working with this stuff.


Necroposting time

AoE attacks are just hacked grenades with a throwTime of 0.

Some time ago the throwTime of grenades (and objectToss) actually became a passable parameter, i.e. throwing a grenade with throwTime 0 and any defaultAngle + range gives a “relative AoE”