function OSI.SetMechanicIconForUnit(
    displayName,    -- display name of the affected player
    texture,        -- icon texture path
    size,           -- optional icon size
    color,          -- optional icon color {r,g,b}
    offset,         -- optional icon offset in meters
    callback        -- optional callback function
)
function OSI.RemoveMechanicIconForUnit(
    displayName     -- display name of the affected player
)

local ADDON_NAME  = "MyAddonName"
local MY_TEXTURE  = "myaddonname/myiconpath/myicontexture.dds"
local MECHANIC_ID = 12345
EVENT_MANAGER:RegisterForEvent( ADDON_NAME, EVENT_ADD_ON_LOADED, function( _, addonName )
    if addonName ~= ADDON_NAME then return end
    EVENT_MANAGER:UnregisterForEvent( ADDON_NAME, EVENT_ADD_ON_LOADED )
    EVENT_MANAGER:RegisterForEvent( ADDON_NAME, EVENT_EFFECT_CHANGED, function( _, changeType, _, _, unitTag )
        -- check if OdySupportIcons is active and the affected unit is a player
        if OSI and OSI.SetMechanicIconForUnit and IsUnitPlayer( unitTag ) then
            -- retrieve the displayname of the affected player
            local displayName = GetUnitDisplayName( unitTag )
            -- if the player gained the mechanic effect...
            if changeType == EFFECT_RESULT_GAINED then
                -- assign your icon to the affected player and make it bigger than other icons
                OSI.SetMechanicIconForUnit(
                    displayName,             -- display name of the affected player
                    MY_TEXTURE,              -- icon texture path
                    OSI.GetIconSize() * 1.5, -- optional icon size
                    { 1, 1, 1 },             -- optional icon color {r,g,b}
                    0,                       -- optional icon offset in meters
                    function( data )         -- optional callback function
                        -- simple bounce animation along the y-axis
                        data.offset = 0.5 + 0.5 * math.sin( GetGameTimeMilliseconds() / 1000 * 2 )
                        -- the data object passed to the callback function contains:
                        -- displayName, unitTag, texture, size, color, offset
                    end
                )
            -- if the player lost the mechanic effect...
            elseif changeType == EFFECT_RESULT_FADED then
                -- remove your icon from the formerly affected player
                OSI.RemoveMechanicIconForUnit( displayName )
            end
        end
    end )
    EVENT_MANAGER:AddFilterForEvent( ADDON_NAME, EVENT_EFFECT_CHANGED, REGISTER_FILTER_ABILITY_ID, MECHANIC_ID )
    EVENT_MANAGER:AddFilterForEvent( ADDON_NAME, EVENT_EFFECT_CHANGED, REGISTER_FILTER_UNIT_TAG_PREFIX, "group" )
end )

function OSI.CreatePositionIcon(
    x, y, z,    -- world coordinates
    texture,    -- icon texture path
    size,       -- optional icon size
    color,      -- optional icon color {r,g,b}
    offset,     -- optional icon offset in meters
    callback    -- optional callback function
)
function OSI.DiscardPositionIcon(
    icon        -- position icon object
)

/script OSI.PrintMyPosition()

local ADDON_NAME = "MyAddonName"
local MY_TEXTURE = "myaddonname/myiconpath/myicontexture.dds"
local MY_ICON    = nil
EVENT_MANAGER:RegisterForEvent( ADDON_NAME, EVENT_ADD_ON_LOADED, function( _, addonName )
    if addonName ~= ADDON_NAME then return end
    EVENT_MANAGER:UnregisterForEvent( ADDON_NAME, EVENT_ADD_ON_LOADED )
    EVENT_MANAGER:RegisterForEvent( ADDON_NAME, EVENT_BOSSES_CHANGED, function()
        -- check is OdySupportIcons is active and supports world position icons
        if OSI and OSI.CreatePositionIcon then
            -- retrieve name of boss
            local boss = GetUnitName( "boss1" )
            -- if we are in Sharpfangs (Deshaan) lair and...
            if boss and boss == "Sharpfang" then
                -- if no icon has been created yet...
                if not MY_ICON then
                    -- create an icon 2.5m above the stone formation and make it bigger than other icons
                    MY_ICON = OSI.CreatePositionIcon(
                        274367, 11022, 213871,   -- world coordinates
                        MY_TEXTURE,              -- icon texture path
                        OSI.GetIconSize() * 1.5, -- optional icon size
                        { 1, 1, 1 },             -- optional icon color {r,g,b}
                        2.5,                     -- optional icon offset in meters
                        function( data )         -- optional callback function
                            -- simple bounce animation along the y-axis
                            data.offset = 2.5 + math.sin( GetGameTimeMilliseconds() / 1000 * 2 )
                            -- the data object passed to the callback function contains:
                            -- texture, size, color, offset
                        end
                    )
                end
            -- if we are somewhere else or Sharpfang is not around and...
            else
                -- if an icon has been created before...
                if MY_ICON then
                    -- discard the icon
                    OSI.DiscardPositionIcon( MY_ICON )
                    MY_ICON = nil
                end
            end
        end
    end )
end )

function OSI.AddCustomIconPack( icons )

local ADDON_NAME  = "MyAddonName"
local MY_TEXTURES = {
    "myaddonname/myiconpath/myicontexture-1.dds",
    "myaddonname/myiconpath/myicontexture-2.dds",
    "myaddonname/myiconpath/myicontexture-3.dds",
}
EVENT_MANAGER:RegisterForEvent( ADDON_NAME, EVENT_ADD_ON_LOADED, function( _, addonName )
    if addonName ~= ADDON_NAME then return end
    EVENT_MANAGER:UnregisterForEvent( ADDON_NAME, EVENT_ADD_ON_LOADED )
    -- check if OdySupportIcons is active and supports custom icon packs
    if OSI and OSI.AddCustomIconPack then
        -- add your list of icons
        OSI.AddCustomIconPack( MY_TEXTURES )
    end
end )

function OSI.AddUniqueIconPack( icons )

local ADDON_NAME  = "MyAddonName"
local MY_TEXTURES = {
    ["@SomePlayer"]    = "myaddonname/myiconpath/myiconforsomeplayer.dds",
    ["@AnotherPlayer"] = "myaddonname/myiconpath/myiconforanotherplayer.dds",
}
EVENT_MANAGER:RegisterForEvent( ADDON_NAME, EVENT_ADD_ON_LOADED, function( _, addonName )
    if addonName ~= ADDON_NAME then return end
    EVENT_MANAGER:UnregisterForEvent( ADDON_NAME, EVENT_ADD_ON_LOADED )
    -- check if OdySupportIcons is active and supports unique icon packs
    if OSI and OSI.AddUniqueIconPack then
        -- add your list of icons
        OSI.AddUniqueIconPack( MY_TEXTURES )
    end
end )