Skip to content
Awful Toolbox
Alerts & Visuals

These are our visual tools that may help to keep the user aware of what's happening, in style.

  • These functions are located directly under the awful namespace.

alert

Displays a toast alert for the user.

alerts

  • Trying to recreate an identical alert while it's still displayed will just extend the duration, so feel free to spam it while it's relevant!

  • We included a lot of customization options so you can get the tone & delivery of your message across clearly, but we also want to keep the theme consistent with other alerts.

  • You can opt for as much or as little customization as you want. All that is required is a message, even the texture is optional.

  • Always returns true so you can include it as part of your conditional expressions for cleaner code.

awful.alert([message / {options}], [texture]) : true

Options:

message string - The message of your alert.

texture integer - SpellID to use as the texture for this alert.

duration float - Lifespan of the alert (not including fade in and fade out animations)

fadeIn float - Duration of the fade in animation. Default 0.175 (cubic-bezier easing)

fadeOut float - Duration of the fade out animation. Default 0.3 (cubic-bezier easing)

bgColor array - The rgb[a] color value (0-1) of the texture background (essentially the shadow, the "mood" of the alert) inside of an array. { r, g, b [,a]}

imgX float - Number of pixels to move the texture on the X axis behind the circular mask.

imgY float - Number of pixels to move the texture on the Y axis behind the circular mask.

imgScale float - The scale of the texture behind the circular mask.

  • Here are some example alerts. I encourage you to /run them in-game and see how they look.
-- nice basic alert, just some text
awful.alert("hi mom")

-- adding a spell texture to the mix.
awful.alert("Sheepy Sheep", 118)

-- some text colors
awful.alert("Sheepy? "..awful.colors.red.."NO.", 118)

-- now a red background to go with that. we'll have to use options now.
awful.alert({
    message = "Sheepy? "..awful.colors.red.."NO.",
    texture = 118,
    bgColor = awful.rgbColors.red
})

-- passing our own custom colors... the color escape won't work through /run in chat. you'll have to write & run this from your routine to test it.
awful.alert({
    message = "Sheepy? |cFF5c9affYES!",
    texture = 118,
    bgColor = {30/255, 60/255, 120/255, 0.95}
})

-- let's see what Meteor looks like...
awful.alert("Meteor!", 153561)

-- hmm, i don't like how the meteor itself is cut off by the mask. i want to move it up and to the left a bit. maybe scale it down too.
awful.alert({
    message="Meteor!",
    texture=153561,
    imgX = 1,
    imgY = 0.55,
    imgScale = 0.875
})
-- nice, that's much better...

textureEscape

Converts spellID or texture ID into a texture escape sequence string for use in alerts, other frames, or prints.

awful.textureEscape(spellID/FileDataID[,size,offsets])
-- texture = freezing trap spellID
-- size 16px
-- offsets "x:y", here am moving it up 2 pixels
local trap = awful.textureEscape(187650, 16, "0:2")

-- now gonna alert and print this
awful.alert(trap .. " the healer!", 187650)
print(trap .. " in the chat!")

Draw

awful.Draw Draws various things ingame - to be expanded with more examples.

local Draw = awful.Draw
Draw(function(draw)
    draw:SetWidth(number) -- Set the width of the draw, such as the width of a Line
    draw:SetColor(r, g, b, a) -- Set the color of the draw, such as the color of a Line

    draw:Line(x1, y1, z1, x2, y2, z2, maxDistance) -- Draw a line from xyz1 to xyz2, maxDistance being how many yards a line can be before it attaches a "new line" to the end of the previous line
    draw:Circle(x, y, z, radius, steps) -- Draw a circle at xyz with a radius and steps, steps being how many lines are used to draw the circle
    draw:Cylinder(x, y, z, radius, height) -- Draw a cylinder at xyz with a radius and height
    draw:Arc(x, y, z, size, arc, rotation) -- Draw an arc at xyz with a size (i.e. length of the arc), arc being how many degrees the arc is, and rotation being the "facing direction" of the arc
    draw:Rectangle(x, y, z, width, length, rotation) -- Draw a rectangle at xyz with a width, length, and rotation
    draw:Outline(x, y, z, radius) -- Draw an outline at xyz with a radius, basically a thick circle
    draw:FilledCircle(x, y, z, radius, steps) -- Draw a filled circle at xyz with a radius and steps
    draw:Triangle(x, y, z, v1, v2, v3, cull, wireframe) -- Draw a triangle at xyz with vertices v1, v2, and v3, cull true/false backface culling, wireframe true/false wireframe around the triangle
    draw:Text(string, font, x, y, z) -- Draw a string of text using the defined font on the provided coordinates. You can reference the awful font by creating it outside of this function as a local, e.g. local AwfulFont = awful.createFont(10, "OUTLINE")
    draw:Texture(config, x, y, z, alphaA) -- Draw a texture at xyz with an alpha value, config being the texture path e.g. {texture = path, width = number, height = number}
end)
General Tools
Config