Hi and Welcome to Plater scripting guide and documentation
More pages on scripting for Plater (see the menu in the right side of this window):
1. What's The Difference Between the Scripting and Modding tabs
Scripts at the Scripting tab run after something specific triggers it, can be:
- Unit Name: Name or npcID of a npc
- Buffs & Debuffs: Buff, debuff name or spellID of an aura
- Spell Casting: Spell name or spellID of a spell being cast.
Script at the Modding tab run after an event is triggered on the nameplate it self, these are more generic and run for all nameplates regardless the unit, buff or spell shown, a few examples:
- Nameplate Created: when the game just created a new nameplate frame, this happen only once for each nameplate.
- Nameplate Added: when a new mob is shown in the player screen and the game placed a nameplate above the mob head.
- Nameplate Removed: when the game removed a nameplate from the screen.
- Nameplate Updated: when Plater updated the nameplate.
- Cast Start: when any nameplate shown in the screen starts a cast.
1.1 When to create a script in the Scripting tab?
If the goal is to modify something for a specific aura, cast or npc, the scripting tab is used.
- The debuff 'Shadow Word: Pain" from shadow priest.
- A shadow priest starts to cast Mind Control.
- A shadow priest pet named 'Mindbender'.
1.2 When to create a script in the Modding tab?
At any other case when there's no specific unit, aura or cast.
- Change the color of your current target.
- A unit is below 50% health.
- Need to track if a unit if attacking someone in the raid.
2. Understanding Code Types
At the scripting tab, there's a dropdown box below the text editor called "Code Type", clicking there there's 4 options to select:
- Constructor: run only once when the script run for the first time, use it to create settings, frames, textures, animations or functions.
- OnShow: run once for each time the script is triggered, use to show or play things created in the constructor script.
- OnUpdate: after Plater finished updating the area affected by the script, this script runs. Use it to change colors, change names, etc.
- OnHide: when the trigger isn't there anymore, e.g. a debuff finished, the cast has stopped, the unit has died etc. Use to restore changes made and hide any custom features.
2.1 Code Types in the Modding Tab
All options in the Modding tab is a code type, they run after the event is triggered.
These code types can run after the event happed to the nameplate and only run for that nameplate, example: 'Nameplate Added' will trigger only that the nameplate that has been added.
Some events will trigger the script to run on all nameplates shown on the screen, example: Target Changed, when the player changes its target the code will run once for each nameplate shown in the screen.
Hover over an option to see the description in the tooltip.
3. Function Parameters
All scripts in both Scripting and Modding tabs receive 4 parameters:
- unitId: the ID to udentify the unit, use for example on UnitName (unitId), UnitClass (unitId).
- unitFrame: frame where the health bar, cast bar and auras are attached, it also holds several information about the nameplate shown.
- envTable: a standard lua table to use to share information among code types within the script, example: a config set (envTable.Color = 'red') in the constructor code can be accessed by the OnUpdate code (Plater.SetNameplateColor (envTable.Color)).
- self: if the frame that triggered the script, for an Aura is the aura icon (frame) shown, the cast bar statusbar frame for cast and unitFrame for everything else.
4. Constructor Code
Both tabs has in common the constructor code, as explained above, it run only once when the script run for the first time.
This script is guaranteed to run before any other code types within the script.
The image below shows the code type: constructor selected and the code editor showing some lines creating some widgets and storing data.
5. Nameplate Structure Hierarchy
6. Getting the Unit Information from the Nameplate
Several data are stored within the nameplate, they can be query by the script at any time:
unitFrame.namePlateUnitGUID: guid of the unit.
unitFrame.namePlateNpcId: npc id.
unitFrame.namePlateIsQuestObjective: true if the unit is an objective of a quest.
unitFrame.namePlateUnitReaction: reaction number (<= 3 enemy | 4 = neutral | 5 >= friendly).
unitFrame.namePlateClassification: type of the unit ('normal', 'minor', 'elite', 'rare', etc).
unitFrame.namePlateInRange: true if the unit is in range of the player.
unitFrame.namePlateUnitName: unit's name.
unitFrame.namePlateUnitNameLower: unit's name but using lower case letters.
unitFrame.namePlateIsTarget: true if the unit is the current target of the player.
unitFrame.namePlateThreatPercent: amount of threat the player has towards the unit.
unitFrame.PlayerCannotAttack: true if the player cannot attack the unit.
unitFrame.InExecuteRange: true if the unit's health is within the execute range of the player character.
local healthBar = unitFrame.healthBar
healthBar.currentHealth: current amount of health.
healthBar.currentHealthMax: max amount of health.
local castBar = unitFrame.castBar
castBar.casting: true if the spell is a regular cast (not a channeling spell).
castBar.channeling: true if the spell is a channeling spell.
castBar.interrupted: true if the spell got interrupted.
castBar.failed: true if the spell failed by some reason.
castBar.finished: true if the cast is finished (by any reason).
castBar.canInterrupt: true if the spell can be interrupted.
castBar.spellID: spellID of the spell currently being cast.
castBar.spellName: name of the spell.
castBar.spellTexture: icon texture of the spell.
castBar.spellStartTime: when the spell started (GetTime()).
castBar.spellEndTime: when the spell will finish (GetTime()).
castBar.value: current value set in the cast bar, this is a number between the start and end time.
auraIcon.spellId: the aura's spellID
auraIcon.SpellName: aura name.
auraIcon.InUse: true if the icon is currently shown above the nameplate.
auraIcon.IsShowingBuff: true if the icon is showing a buff (is a debuff otherwise).
auraIcon.IsPersonal: true if this aura icon is anchored in the personal bar.
7. Getting even more Information from the envTable (only scripts on Scripting tab)
Inside the envTable there's information about the unit, cast or aura icon shown.
An envTable of an Aura trigger holds:
envTable._SpellID: the aura's spellID
envTable._SpellName: aura's name.
envTable._Texture: aura's icon texture.
envTable._Caster: unitID of who casted the aura.
envTable._StackCount: amount of the stacks the aura has.
envTable._Duration: total duration the aura has.
envTable._StartTime: when the aura started.
envTable._EndTime: when the aura will end.
envTable._RemainingTime: amount of time the aura still has.
An envTable of a Cast trigger holds:
envTable._RemainingTime: how much time until the cast is done.
envTable._CastPercent: percent of the cast (0 to 100).
An envTable for Unit Name or UnitID trigger holds:
envTable._NpcID: the ID of the npc shown.
envTable._UnitName: name of the npc.
envTable._UnitGUID: GUID of the npc.
envTable._HealthPercent: percent of the health (0 to 100).
8. Script Examples (Scripting tab)