Cookbook

Relative X, Y coordinates based on resolution

When trying to set position relative to Right side of screen or Bottom side of screen (or even center of screen), you need to do something like screenWidth - X, xcreenHeight - Y but width and height are absolute pixel count, while ToS X,Y coord system is based on a relative size.

Thus in the above case, we need to divide width/height by ratio:

    local relativeWidth = ui.GetSceneWidth() / ui.GetRatioWidth();
    local relativeHeight = ui.GetSceneHeight() / ui.GetRatioHeight();
    local xPos = relativeWidth - xDisplacement;
    local yPos = relativeHeight - yDisplacement;
    frame:SetPos(xPos, yPos);

Control Transparency

icon:SetColorTone("00FFFFFF")
icon:SetColorTone("FFFFFFFF")
-- First 1 byte hex from 00 - FF sets transparency

Playing visual and audio effects

Often times you might want to create an addon that alerts the user about something using a visual or audio effect. The two APIs that seem to work for this is:

-- play effect
effect.PlayActorEffect(actor, effectName, nodeName, lifeTime, scale, x, y, z)
-- play audio
imcSound.PlaySoundEvent(effectName);

While the authoritative list of available effect and sound effects are unknown, the best we have to work with is the forkparticle.xml file.

If we take a look at one of the entries:

<Particle name="F_spin039_sword_orange_reverse_Sawblade_Shield" file="F_spin039_sword_orange_reverse" time="1" scale="5" sound="skl_eff_vibora_sawblade_shield" fadeSound="FALSE" looptime="0.000000" sounddelay="0.100000" paused="NO" rotate="NO" attach="NO" render="NORMAL" color="255;255;255;255" is2D="FALSE" softParticleFactor="5" useReverse="FALSE" preScale="1.0" preScaleXYZ="" useAttach="TRUE" attachNodeName="None"/>

Here we see that we can pass in F_spin039_sword_orange_reverse_Sawblade_Shield as effectName for PlayActorEffect, or skl_eff_vibora_sawblade_shield as effectName for PlaySoundEvent.

While playing sound effect is fairly simple due to it only receiving a single parameter, effect.PlayActorEffect has a little more details.

effect.PlayActorEffect

• actor CFSMActor type. Known way to get the actor object is through world.GetActor(handle) or world.GetActorByFamilyName(familyName). To play on yourself, session.GetMyHandle() can be used to get pc handle, session.GetTargetHandle() can be used to get target handle. GetObjects to find nearby objects can be converted into a list of nearby handles, as seen in this example first party code.
  • A handle is an ID that represents an object nearby (npc, monster, pc, boss, etc)
  • You can also play effect on an actor through <myActor>:GetEffect():PlayEffect(effectName, scale, offsetEnum). Value for offsetEnum is unknown, and can be set as nil
• effectName a string effect name. Seems that the effects in forkparticle.xml are the only ones that work.
• nodeName a node on the character where the effect's centroid position will be based on. For instance, Dummy_bufficon is a nodeName that represents the area on top of a player's head where usually buffs are displayed. List of authoritative nodes are unknown, you can find all used nodeNames within animation.xml files, and skill item animation files as well.
• lifeTime time in seconds of how long the animation will remain
• scale size scale. Invisible when 0, and can be very large. When experimenting, start with a value around 1~5 and shrink/grow as needed.
• x rotation in x axis
• y rotation in y axis
• z rotation in z axis

Additional resources to study:

• Most information about effect playing comes from reaction.lua. However, I have yet to understand the full depth of playing a visual effect. For instance, I have still not been able to successfully invoke effect.PlayGroundEffect().