Auras and Emanations

This extension allows you to add auras to any character in a variety of styles.

Features

• ✨ Create auras from shapes, shader effects, or images.
• 🟩 Auras will display the correct shape for the current grid type and grid measurement type. (e.g when using Chebyshev / Chessboard D&D 5e distance, auras will be square)
• ↔️ Auras will automatically resize after tokens are scaled, so that their boundary is the correct distance away.
• 🎨 Manage any number of auras with any color, opacity, or style.
• 🛠️ Create aura presets for commonly used effects.

How to use

Adding an aura

Select one or more character tokens, then right click and click the 'Add Aura' item that appears on the context menu. You can also press 'E' (for Emanation - A for Aura was taken :P) while the context menu is open to add one quickly.

The aura will be centered on the source's origin point (the center of the controls when you edit the item). This means that if the image's center is offset from the origin, the aura will not appear in the center of the image. You can adjust the aura positioning using the 'Reposition Auras' feature below.

Editing aura parameters

When any selected token has at least one aura, you will see the 'Edit Auras' menu option (with the same 'E' shortcut), which lets you manage auras for those characters through the 'Aura Settings' action in the top left.

You can also open the action in the 'Edit' tab and then select tokens to add or edit auras.

Menu options:

• Style: Display style of the aura (see below).
• Size: Size of the aura, in the same units as the grid.
• Color: Aura color. Editable with your browser's native color picker. By default, the color will be your player color.
• Opacity: Aura opacity.
• Image: For image auras, selects which image asset to use as the aura.
• Delete: Remove this aura from the character.
• Copy to Clipboard: Copy this aura's settings to your OS clipboard.
• New: Add another aura to the characters using the top preset from the 'Defaults' tab. If multiple characters are selected, this button will add a new aura to all of them.
• New (arrow): Add another aura to the characters using a preset from the menu.
• Paste: Allows you to add a previously-copied aura to a token.
• Delete All: Remove all auras from the selected characters.

Options under 'Advanced Options':

• Visibility: Lets you control which players can see the aura.
• Layer: Which layer the aura is drawn on. Some aura types require the POST_PROCESS layer, and cannot be changed.
• Blend Mode: For shader-based auras, sets the graphical blend mode for the shader. Ideas: 'PLUS' with the 'Glow' aura is good for simulating lights, and with a pure white 'Range' aura, 'DIFFERENCE' creates an area of negative color, and 'SATURATION' creates an aura that makes the world inside it grayscale.
• Shape Override: Set the shape of an aura manually, rather than auras taking their shapes from the grid settings. This setting overrides any scene-global aura shape setting.

Editing multiple auras at once

If you select multiple tokens which all share an aura, you can edit that aura on all the tokens at once. You will see a list of which tokens you are editing above the aura settings.

Resizing tokens

When you drag to resize a token, the aura will change size after you let go.

Changing grid types

When you change the grid type or measurement type, auras will reshape to be appropriate for the new settings.

Repositioning auras

You can reposition auras relative to their source token using the reposition tool:

• Click the Reposition Auras button at the top right of the 'Edit Auras' tab to activate reposition mode.
• While the tool is active, draggable icons will appear over each aura. Drag an icon to move the corresponding aura's center relative to its source token.
• Double-click an icon to reset the aura to its original (centered) position.
• Click the reposition button again to exit reposition mode.

This is useful for effects like torches, where you want the aura to emanate from a specific part of the token (e.g., the head of a torch) rather than the center.

Managing Presets

To create presets for new auras, open the Aura Settings action menu in the top left and go to the 'Defaults' tab. These settings are saved to your browser's local storage, so they persist across game sessions (unless you clear your browser data).

Controls:

• Preset Name: Give your preset an informative name. These names show up under the 'New' button dropdown in the Edit tab.
• New: Create a new preset.
• Delete: Delete a preset. You must always have at least one preset, so you can't delete the last one.
• Paste: Paste a previously copied set of aura settings as a preset.

You can also create preset groups, which combine multiple presets into one. To create a preset group, click the arrow next to 'New' in the Defaults tab and click "Create Preset Group".

Editing preset groups:

• Preset Group Name: Give your preset group a name.
• Presets: Here you can choose which presets belong to this preset group. Presets can belong to multiple groups, but you can't put a group inside another group.

Changing settings

In the 'Settings' tab, there are a couple settings to configure the extension:

• Enable Context Menu: Whether to show the 'Add Aura' and 'Edit Aura' items mentioned above. Turn this off to declutter your context menu - you can still edit auras in the action popover.
• Show advanced options: Whether to show some advanced menu items in certain menus like the aura style menu, the layer selection menu, and the blend mode menu.

Scene Settings

The GM can also access scene-global settings under the Aura Settings action menu in the 'Settings' tab.

• Shape to grid: When enabled, causes auras in the current scene to try to trace out the outline of grid squares within range. When disabled, auras trace the exact set of points within range of the source, even when that cuts through the middle of grid squares.
• Override Shape: When set, causes auras to take on the specified shape, rather than conforming to a shape that traces out the points a certain distance away from the source based on the grid's current measurement settings.

Aura Styles

This extension supports several different aura styles. The different types are listed below.

Simple

A filled area with a solid outline. The color control sets the color of both the fill and stroke, and the opacity controls the opacity of the fill.

Image

An image from your assets. You can find some fun effect images from https://library.jb2a.com.

Bubble

An area with a gradient that gets more opaque towards the edges. High opacity values are recommended.

Inspired by these AoE tokens.

Glow

An always-circular glow around the token that's lighter in the center. Useful for simulating torches!

Range

A rangefinder which steps from white to the aura color at each discrete grid unit. Supports all grid types. Darker aura colors are recommended for contrast.

Spirits

A fancy one just for fun! Displays animated trails that circle your character while changing color.

Solid

A utility aura - just draws a flat single color shape. Can be used for interesting effects if combined with blend modes (e.g use the COLOR blend mode to set everything in a circle behind the aura to a certain hue).

Distort

Bends space around it. Simulate black holes or reality-warping effects. Use the slider in the controls to scale the warping factor.

Calling this extension from other extensions

If you're another extension developer, you can automate managing auras with this API. Create an object message of one of these types:

interface CreateAurasMessage {
    type: "CREATE_AURAS";
    /**
     *  Item IDs for character images that will receive the aura.
     */
    sources: string[];
    /**
     * Aura size, e.g 5 for 5ft.
     */
    size: number;
    /**
     * Style of aura to create. If not provided, the current player's default style will be used.
     */
    style?:
        | "Simple"
        | "Image"
        | "Bubble"
        | "Glow"
        | "Range"
        | "Spirits"
        | "Distort"
        | "Solid";
    /**
     * Hex code, e.g "#d00dad". If not provided, the current player's default color will be used.
     */
    color?: string;
    /**
     * Number from 0 (fully transparent) to 1 (fully opaque). If not provided, the current player's default opacity will be used.
     */
    opacity?: number;
    /**
     * ID of player this aura will be visible to. If not provided, the aura will be visible to everyone.
     * If set to null, the aura will not be visible.
     */
    visibleTo?: string | null;
    /**
     * Which Owlbear Rodeo layer the aura will be on. If not provided, the 'DRAWING' layer
     * will be used.
     */
    layer?: Layer;
    /**
     * Blend mode for effect-based auras. Only used if the `style` parameter is an effect type. If not provided,
     * the default SRC_OVER value will be used.
     */
    blendMode?: BlendMode;
    /**
     * Details for image-based auras. Must be provided if and only if the `style` parameter is "Image".
     */
    imageBuildParams?: {
        image: ImageContent;
        grid: ImageGrid;
    };
}

interface RemoveAurasMessage {
    type: "REMOVE_AURAS";
    /**
     *  Item IDs for character images that will have all auras removed.
     */
    sources: string[];
}

export interface CreateAurasPresetsMessage {
    type: "CREATE_AURAS_PRESETS";
    /**
     *  Item IDs for character images that will receive auras.
     */
    sources: string[];
    /**
     * Preset or preset group names to create auras from.
     */
    presets: string[];
}

Then send a local broadcast with the message:

await OBR.broadcast.sendMessage("com.desain.emanation/message", message, {
    destination: "LOCAL",
});

Support

If you need support for this extension you can message me in the Owlbear Rodeo Discord @Nick or open an issue on GitHub.