AdamsAddonsDecalRegistry.md

Tip

If you aren't familiar with decal registry, please refer to the wiki page here

How to use

In order to use these decal registry attributes, you need to have Adam's Add-ons installed. Apart from that, they don't require anything to set up, and can be used like vanilla attributes. Map editors can't detect custom decal registry attributes, so remember to manually add this helper as a dependency.

Default values

Decal registry attributes can have variables that add further customization, and these variables have default values. It is good practice not to change a variable if the default works for you. For example, most bool variables are "false" by default, so writing exampleVariable="false" for them is redundant. Some variables may override or ignore others.

Attribute stacking

Most attributes can be used with others, and can be applied to a decal multiple times with different variables.
Sometimes the order in which the attributes are applied also matters. If you find an interaction that doesn't work,
contact me (Adam Korinek) on Discord.

Cyclical processes

Some of the following attributes create cyclical processes, these all have four common variables that can be changed:

• speed - how fast the process is, it's easiest to think of 1 as 100% (default: "1.0").
• offset - can be used to define a starting offset, requires some experimentation (default: "0.0").
• randomize - if true, the offset variable will be ignored and starting offset will instead be randomized (default: "false").
• updateFlag - if defined, the process will only be active when the given flag is set (default: "").

Decal Registry Attributes

Rotate (adamsaddons.rotate)

Makes the decal rotate with a constant speed.

Variables:

• speed - how fast the decal spins. Negative speed means counter clockwise rotation. By default this uses radians per second, adding "°" after the number will translate to degrees per second instead. (default: "0.0").
• addX and addY - how much the decal rotates as it is moving horizontally or vertically.
  These two are designed to be used with static movers (default: "0.0").
• addWind - adds further rotation based on the strength of the wind (default: "0.0").
• delay - how many seconds to wait between each rotation, in case it needs to be less fluid (default: "0.0").
• canFlip - whether the rotation's direction should change if the decal's X or Y scale is negative,
  useful if you want a clockwise and counter clockwise version with one decal registry entry (default: "false").
• flag - if defined, the decal will only rotate when the given flag is set (default: "").

Examples

<adamsaddons.rotate speed="-2.5"/>
<adamsaddons.rotate addX="1" addY="-1"/>
<adamsaddons.rotate speed="2" addWind="1"/>
<adamsaddons.rotate speed="30°" delay="1" flag="rotate_flag"/>

Oscillate (adamsaddons.oscillate)

Gives the illusion that the decal is rotating around the Y-axis.

Variables:

• backPath - what image to use for the back of the decal relative to the Gameplay folder.
  If unchanged, the back will be the same as the front, but mirrored (default: "").
• noFlip - if true, the decal texture won't be mirrored when it is facing backwards.
  This is the default behavior if there is a custom backPath set (default: "false").
• minWidth - the decal's width will never decrease below this value,
  this is to avoid it being thin enough to turn invisible (default: "0.0").

This attribute creates a cyclical process, speed, offset, randomize, and updateFlag can be modified.

Examples

<adamsaddons.oscillate/>
<adamsaddons.oscillate backPath="decals/..."/>
<adamsaddons.oscillate speed="0.5" offset="1"/>
<adamsaddons.oscillate randomized="true" noFlip="true"/>
<adamsaddons.oscillate speed="2" updateFlag="oscillate_flag" minWidth="0.2"/>

Aim (adamsaddons.aim)

Makes the decal face towards the player at all times. This attributes respects the decal's initial direction,
so a decal rotated 180° will face away from the player.

Variables:

• theo - if true, the decal will target a Theo crystal instead of the player (default: "false").
• flag - if defined, the decal will only aim when the given flag is set (default: "").
• flipX and flipY - if either is true, the decal won't rotate, but will instead flip to face towards the target.
  flipX flips horizontally if the target is left of it, flipY flips vertically if the target is above it. (default: "false").

Examples

<adamsaddons.aim/>
<adamsaddons.aim theo="true"/>
<adamsaddons.aim flag="aim_flag"/>
<adamsaddons.aim flipX="true"/>

Pendulum (adamsaddons.pendulum)

Makes the decal swing back and forth like a pendulum. The center of the rotation is still the center of the image.

Variables:

• angle - the angle the swing should cover in degrees (default: "90").

This attribute creates a cyclical process, speed, offset, randomize, and updateFlag can be modified.

Examples

<adamsaddons.pendulum/>
<adamsaddons.pendulum speed="2" offset="1" updateFlag="pendulum_flag"/>
<adamsaddons.pendulum angle="180" randomize="true"/>

Shake (adamsaddons.shake)

Makes the decal shake constantly.

Variables:

• delay - makes the shake less frequent, by slightly waiting between each movement (default: "0.0").
• width and height - they change the intensity of the shake on a given axis,
  the default shake area is a circle, which these two can resize (default: "1.0").
• flag - if defined, the decal will only shake when the given flag is set (default: "").

Examples

<adamsaddons.shake/>
<adamsaddons.shake delay="0.1" flag="shake_flag"/>
<adamsaddons.shake width="2" height="0"/>

Move (adamsaddons.move)

Converts texture rotation into motion by offsetting the decal in the direction it is facing.
Intended to be used with other attributes that change decal rotation.

Variables:

• amount - how much the decal should be offset (default: "0.0").
• locked - if true, the decal texture itself won't rotate visually (default: "false").
• width and height - they multiply the decal's horizontal or vertical movement (default: "1.0").

Examples

<adamsaddons.move amount="30"/>
<adamsaddons.move amount="-10" locked="true"/>
<adamsaddons.move width="0" height="2"/>

In the gif below, move is used with rotate to create an oribiting motion.
The decal textures themselves don't rotate, which is because of locked="true".

Randomize (adamsaddons.randomize)

Offers many ways of granting the decal random properties, all of which are optional.

Variables:

• frame - if true, the decal will use a random frame of its animation forever, instead of animating (default: "false").
• flipX and flipY - whether the decal should randomly flip horizontally or vertically (default: "false").
• rotations - a number that determines how many possible rotations the decal has.
  4 would make it face in either of the cardinal directions (default: "1").
• colors - a list of comma-separated hex color codes, out of which one will be chosen as the decal's tint (default: "").
• shrink - decreases the decal's size with a random amount. This variable defines the smallest it can be,
  a value of "0.5" means it can be anywhere between its full size, and half of it (default: "1.0").
• chance - percentage that determines how likely the decal spawns. If the chance fails, it will be invisible (default: "1.0").
• seeded - if false, instead of a single randomization the decal will be randomzied after each death (default: "true").
• animation - if true, the decal will switch to random frames of its animation instead of going in order (default: "false").

Examples

<adamsaddons.randomize frame="true"/>
<adamsaddons.randomize flipX="true" flipY="true"/>
<adamsaddons.randomize rotations="8"/>
<adamsaddons.randomize colors="00ffff,ff00ff,ffff00"/>
<adamsaddons.randomize shrink="0.25" chance="0.75"/>
<adamsaddons.randomize frame="true" seeded="false"/>
<adamsaddons.randomize animation="true"/>

Fade (adamsaddons.fade)

Makes a decal transparent, or fade in and out between two alpha values. This can be done cyclically, or based on a flag.

Variables:

• alphaFrom - used as the decal's transparency, or one of the values to change between.
  "0" means invisible, "1" means solid (default: "1.0").
• alphaTo - if set, the decal will fade beween alphaFrom and alphaTo (default: "").
• fadeFlag - if defined, the decal fades towards alphaFrom if the flag is set, and alphaTo if it isn't (default: "").

This attribute can create a cyclical process, speed, offset, randomize, and updateFlag can be modified.

Examples

<adamsaddons.fade alphaFrom="0.5"/>
<adamsaddons.fade alphaFrom="0" alphaTo="1"/>
<adamsaddons.fade alphaTo="0" speed="0.5"/>
<adamsaddons.fade alphaFrom="1" alphaTo="0" fadeFlag="fade_flag"/>

Wobble (adamsaddons.wobble)

The decal will cyclically shrink and grow. Can change width and height with different intensity.

Variables:

• width and height - how much the decal's width or height should vary. "0.25" means a range between 75% and 125%.
  By giving width and height opposite signs, the decal will instead behave like on the gif below (default: "0.0").

This attribute creates a cyclical process, speed, offset, randomize, and updateFlag can be modified.

Examples

<adamsaddons.wobble width="0.5" height="0.5"/>
<adamsaddons.wobble width="0.25" height="-0.25" speed="2"/>
<adamsaddons.wobble width="0.5" randomize="true"/>

Depth Change (adamsaddons.depthChange)

Either changes the decal's depth between two values periodically, or sets it based on the decal's position relative to the player.

Variables:

• depthFrom and depthTo - the two depths to change between (default: "0").
• relativeX and relativeY - instead of periodically, depth changes based on whether the player is
  right or left / above or below the decal. relativeX and relativeY shouldn't both be "true" (default: "false").

This attribute can create a cyclical process, speed, offset, randomize, and updateFlag can be modified.

Examples

<adamsaddons.depthChange depthFrom="-100" depthTo="100"/>
<adamsaddons.depthChange depthFrom="250" depthTo="500" speed="0.5"/>
<adamsaddons.depthChange depthFrom="100" depthTo="-100" relativeX="true"/>

Player Attach (adamsaddons.playerAttach)

Attaches the decal to the player at all times.

Variables:

• offsetX and offsetY - custom offset from the player's position. Note, that player position is at the lower middle of the hitbox, so to be properly centered offsetY should be decreased (default: "0.0").
• facing - if true, the decal will face in the same direction as the player (default: "false").
• hairOffset - if true, the decal will be offset based on where the player's hair, and head, is located (default: "false").
• flag - if defined, the decal will only follow the player when the given flag is set (default: "").
• copyScale - if true, the decal's scale will match the player's as it stretches,
  using default offsets is recommended with this option, try resizing the image instead (default: "false").
• preSpawn - if true, the decal will appear at the player's spawn point before the spawn sequence ends (default: "false").

Examples

<adamsaddons.playerAttach/>
<adamsaddons.playerAttach offsetX="5" offsetY="-8" facing="true"/>
<adamsaddons.playerAttach hairOffset="true" copyScale="true"/>
<adamsaddons.playerAttach flag="attach_flag" preSpawn="true"/>

Camera Attach (adamsaddons.cameraAttach)

The decal will move with the camera, much like a styleground.

Variables:

• offsetX and offsetY - custom offset from the center of the screen (default: "0.0").
• flag - if defined, the decal will only follow the camera when the given flag is set (default: "").

Examples

<adamsaddons.cameraAttach/>
<adamsaddons.cameraAttach offsetX="-8" offsetY="-8"/>
<adamsaddons.playerAttach flag="attach_flag"/>

Debris (adamsaddons.debris)

Meant to be used after the staticMover attribute, the decal will turn into debris once the block it attaches to breaks.

Variables:

• path - what image to use for the debris relative to the Gameplay folder.
  If unchanged, it will be the same as the decal (default: "").
• impactAudio - the sound the debris should make when hitting the ground (default: "event:/game/general/debris_dirt").
• fromPlayer - if true, the debris will be launched away from the player, instead of the top middle of the block.
  This is the behavior of dash block debris (default: "false").
• fromBadeline - if true, the debris will be launched away from a badeline boss (default: "false").

Examples

<adamsaddons.debris/>
<adamsaddons.debris path="debris/..."/>
<adamsaddons.debris impactAudio="event:/game/general/debris_wood" fromPlayer="true"/>

In the gif below, decals are placed over the spikes so that they turn into debris along with the block.

Global (adamsaddons.global)

The affected decal will remain active even if the player leaves the room it is in. If the decal is visible in multiple rooms,
it is advised to place a copy in both rooms, the attribute will make sure that only one copy is loaded at a time.

Variables:

• transitionUpdate - whether the decal should animate during screen transitions (default: "false").
• frozenUpdate - whether the decal should animate during freeze frames (default: "false").
• pauseUpdate - whether the decal should animate while the game is paused (default: "false").

Examples

<adamsaddons.global/>
<adamsaddons.global transitionUpdate="true"/>
<adamsaddons.global frozenUpdate="true" pauseUpdate="true"/>

Animate On Flag (adamsaddons.animateOnFlag)

The decal will only animate if the specified flag is true, or will advance a single frame every time the flag turns on.

Variables:

• flag - the flag that decides whether the decal should be animated or not (default: "").
• singleFrame - if true, the decal changes frame each time the flag turns on (default: "false").

Examples

<adamsaddons.animateOnFlag flag="animate_flag"/>
<adamsaddons.animateOnFlag flag="advance_flag" singleFrame="true"/>

Mouse Attach (adamsaddons.mouseAttach)

The decal will follow the mouse cursor.

Variables:

• offsetX and offsetY - custom offset from the cursor (default: "0.0").
• flag - if defined, the decal will only follow the mouse when the given flag is set (default: "").

Examples

<adamsaddons.mouseAttach/>
<adamsaddons.mouseAttach offsetX="-8" offsetY="-8"/>
<adamsaddons.mouseAttach flag="attach_flag"/>