Skip to content

API Utility functions

Jump to bottom
LenweSaralonde edited this page Feb 21, 2021 · 18 revisions

Utility functions

Functions

Musician.Utils.Print

Display a message in the console

Musician.Utils.Print(msg)

Arguments

  • msg (string)

Musician.Utils.Debug

Print debug stuff in the console

Musician.Utils.Debug(module, ...)

Arguments

  • module (string)
  • ... (string)

Musician.Utils.PrintError

Display an error message in the console

Musician.Utils.PrintError(msg)

Arguments

  • msg (string)

Musician.Utils.Error

Display an error message in a popup

Musician.Utils.Error(msg)

Arguments

  • msg (string)

Musician.Utils.Popup

Display a message in a popup

Musician.Utils.Popup(msg, callback, force)

Arguments

  • msg (string)
  • callback (function)
  • force (boolean)

Musician.Utils.Highlight

Highlight text

highlightedText = Musician.Utils.Highlight(text, color)

Arguments

  • text (string)
  • color (string|Color)

Returns

  • highlightedText (string)

Musician.Utils.RemoveHighlight

Remove text coloring

text = Musician.Utils.RemoveHighlight(highlightedText)

Arguments

  • highlightedText (string)

Returns

  • text (string)

Musician.Utils.GetColorCode

Get color code from RGB values

colorCode = Musician.Utils.GetColorCode(r, g, b)

Arguments

  • r (number) 0-1
  • g (number) 0-1
  • b (number) 0-1

Returns

  • colorCode (string)

Musician.Utils.FormatText

Format text, adding highlights etc.

formattedText = Musician.Utils.FormatText(text)

Arguments

  • text (string)

Returns

  • formattedText (string)

Musician.Utils.GetLink

Get hyperlink

link = Musician.Utils.GetLink(command, text, ...)

Arguments

  • command (string)
  • text (string)
  • ... (string)

Returns

  • link (string)

Musician.Utils.GetPlayerLink

Get player hyperlink

playerLink = Musician.Utils.GetPlayerLink(player)

Arguments

  • player (string)

Returns

  • playerLink (string)

Musician.Utils.GetFullPlayerName

Get player full name with realm slug or Battle.net account name if a Battle.net game account ID is provided

fullPlayerName = Musician.Utils.GetFullPlayerName(player)

Arguments

  • player (string)

Returns

  • fullPlayerName (string)

Musician.Utils.FormatPlayerName

Get player name for display

formattedPlayerName = Musician.Utils.FormatPlayerName(player)

Arguments

  • player (string)

Returns

  • formattedPlayerName (string)

Musician.Utils.IsBattleNetID

Return true when the provided player name is a Battle.net ID

isBattleNetID = Musician.Utils.IsBattleNetID(playerName)

Arguments

  • playerName (string)

Returns

  • isBattleNetID (boolean)

Musician.Utils.GetBattleNetGameAccountID

Get Battle.net game account ID from the Battle.net account ID.

battleNetGameAccountId = Musician.Utils.GetBattleNetGameAccountID(battleNetAccountId)

Arguments

  • battleNetAccountId (string)

Returns

  • battleNetGameAccountId (string)

Musician.Utils.IsBattleNetGameAccountOnline

Indicates whenever the provided game account ID is online

isOnline = Musician.Utils.IsBattleNetGameAccountOnline(gameAccountId)

Arguments

  • gameAccountId (int)

Returns

  • isOnline (string)

Musician.Utils.GetChatIcon

Return the code to insert an icon in a chat message or a text string

chatIcon = Musician.Utils.GetChatIcon(path, r, g, b)

Arguments

  • path (string)
  • r (number) 0-1 _(default=0)
  • g (number) 0-1 _(default=0)
  • b (number) 0-1 _(default=0)

Returns

  • chatIcon (string)

Musician.Utils.GetPlayerPosition

Get the player position in the 3D world

posY, posX, posZ, instanceID = Musician.Utils.GetPlayerPosition()

Returns

  • posY (number)
  • posX (number)
  • posZ (number) Always 0
  • instanceID (number)

Musician.Utils.DisplayEmote

Display a faked emote

Musician.Utils.DisplayEmote(player, playerGUID, message)

Arguments

  • player (string)
  • playerGUID (string)
  • message (string)

Musician.Utils.RemoveChatMessage

Remove a chat message by its line ID

Musician.Utils.RemoveChatMessage(lineID)

Arguments

  • lineID (int)

Musician.Utils.ReadBytes

Read some bytes from a string and remove them

data, str = Musician.Utils.ReadBytes(str, bytes)

Arguments

  • str (string)
  • bytes (int)

Returns

  • data (string) read bytes
  • str (string) new string

Musician.Utils.PackNumber

Pack an integer number into a string

data = Musician.Utils.PackNumber(num, bytes)

Arguments

  • num (int) integer to pack
  • bytes (int) number of bytes

Returns

  • data (string)

Musician.Utils.UnpackNumber

Unpack a string into an integer number

num = Musician.Utils.UnpackNumber(data)

Arguments

  • data (string)

Returns

  • num (int)

Musician.Utils.Base64Decode

Decode base 64 string

Lua 5.1+ base64 v3.0 (c) 2009 by Alex Kloss alexthkloss@web.de

licensed under the terms of the LGPL2

http://lua-users.org/wiki/BaseSixtyFour

str = Musician.Utils.Base64Decode(data)

Arguments

  • data (string)

Returns

  • str (string)

Musician.Utils.Base64Encode

Encode base 64 string

Lua 5.1+ base64 v3.0 (c) 2009 by Alex Kloss alexthkloss@web.de

licensed under the terms of the LGPL2

http://lua-users.org/wiki/BaseSixtyFour

@return string

Musician.Utils.Base64Encode(data)

Arguments

  • data (string)

Musician.Utils.PackTime

Pack a time or duration in seconds into a string

data = Musician.Utils.PackTime(seconds, bytes, fps)

Arguments

  • seconds (float)
  • bytes (int) Number of bytes
  • fps (float) Precision in frames par second

Returns

  • data (string)

Musician.Utils.UnpackTime

Unpack a string into a time or duration in seconds

seconds = Musician.Utils.UnpackTime(data, fps)

Arguments

  • data (string)
  • fps (float) Precision in frames par second

Returns

  • seconds (float)

Musician.Utils.PackPlayerGuid

Pack player GUID into a 6-byte string

data = Musician.Utils.PackPlayerGuid()

Returns

  • data (string)

Musician.Utils.UnpackPlayerGuid

Unpack player GUID from string

guid = Musician.Utils.UnpackPlayerGuid(str)

Arguments

  • str (string)

Returns

  • guid (string)

Musician.Utils.PackPlayerPosition

Pack player position into a 18-byte chunk string

data = Musician.Utils.PackPlayerPosition()

Returns

  • data (string)

Musician.Utils.UnpackPlayerPosition

Unpack player position from chunk string

posY, posX, posZ, instanceID, guid = Musician.Utils.UnpackPlayerPosition(str)

Arguments

  • str (string)

Returns

  • posY (number)
  • posX (number)
  • posZ (number)
  • instanceID (int)
  • guid (string)

Musician.Utils.FromHex

Convert hex string to string

str = Musician.Utils.FromHex(hex)

Arguments

  • hex (string)

Returns

  • str (string)

Musician.Utils.ToHex

Convert string to hex string

hex = Musician.Utils.ToHex(str)

Arguments

  • str (string)

Returns

  • hex (string)

Musician.Utils.SongIsPlaying

Return true if a song is actually playing and is audible

isPlaying = Musician.Utils.SongIsPlaying()

Returns

  • isPlaying (boolean)

Musician.Utils.MuteGameMusic

Start or stop the actual game music if a song can actually be heard

Musician.Utils.MuteGameMusic(force)

Arguments

  • force (boolean)

Musician.Utils.SetInstrumentToysMuted

Mute or unmute music from instrument toys

Musician.Utils.SetInstrumentToysMuted(isMuted)

Arguments

  • isMuted (boolean)

Musician.Utils.GetNormalizedRealmName

Return the normalized realm name the player belongs to

Safer than the standard GetNormalizedRealmName() that may return nil sometimes

realmName = Musician.Utils.GetNormalizedRealmName()

Returns

  • realmName (string)

Musician.Utils.GetRealmLocale

Return the short locale code of the realm the player belongs to

locale = Musician.Utils.GetRealmLocale()

Returns

  • locale (string) 'en', 'fr' etc.

Musician.Utils.NormalizePlayerName

Return the normalized player name, including realm slug

normalizedPlayerName = Musician.Utils.NormalizePlayerName(playerName)

Arguments

  • playerName (string)

Returns

  • normalizedPlayerName (string)

Musician.Utils.NormalizeSongName

Return the normalized song name

normalizedSongName = Musician.Utils.NormalizeSongName(songName)

Arguments

  • songName (string)

Returns

  • normalizedSongName (string)

Musician.Utils.SimplePlayerName

Return the simple player name, including the realm slug if needed

simpleName = Musician.Utils.SimplePlayerName(playerName)

Arguments

  • playerName (string)

Returns

  • simpleName (string)

Musician.Utils.PlayerRealm

Return the player realm slug

realmSlug = Musician.Utils.PlayerRealm(playerName)

Arguments

  • playerName (string)

Returns

  • realmSlug (string)

Musician.Utils.PlayerIsInGroup

Return true if the player is in my party or raid

isInMyGroup = Musician.Utils.PlayerIsInGroup(playerName)

Arguments

  • playerName (string)

Returns

  • isInMyGroup (boolean)

Musician.Utils.PlayerIsMyself

Return true if the provided player name is myself

isMyself = Musician.Utils.PlayerIsMyself(playerName)

Arguments

  • playerName (string)

Returns

  • isMyself (boolean)

Musician.Utils.PlayerIsOnSameRealm

Return true if the provided player name is on the same realm or connected realm as me

isOnSameRealm = Musician.Utils.PlayerIsOnSameRealm(playerName)

Arguments

  • playerName (string)

Returns

  • isOnSameRealm (boolean)

Musician.Utils.PlayerGuidIsVisible

Return true if the player whose GUID is provided is visible (loaded) by the game client

isVisible = Musician.Utils.PlayerGuidIsVisible(guid)

Arguments

  • guid (string)

Returns

  • isVisible (boolean)

Musician.Utils.Ellipsis

Shortens the UTF-8 text with ellipsis if its size in bytes is longer than specified

ellipsisText = Musician.Utils.Ellipsis(text, maxBytes)

Arguments

  • text (string)
  • maxBytes (int)

Returns

  • ellipsisText (string)

Musician.Utils.GetMsg

Returns localized message

localizedMsg = Musician.Utils.GetMsg(msg, locale)

Arguments

  • msg (string)
  • locale (string) Defaults to the realm locale (optional)

Returns

  • localizedMsg (string)

Musician.Utils.GetPromoEmote

Return the "Player is playing music" emote with promo message

promoEmote = Musician.Utils.GetPromoEmote()

Returns

  • promoEmote (string)

Musician.Utils.HasPromoEmote

Return true if the message contains the promo emote, in any language

hasPromoEmote, isFullPromoEmote = Musician.Utils.HasPromoEmote(message)

Arguments

  • message (string)

Returns

  • hasPromoEmote (boolean)
  • isFullPromoEmote (boolean) true if the emote contains the part invinting other players to install Musician

Musician.Utils.ResetFullPromoEmoteCooldown

Mark the full promo emote as recently seen

Musician.Utils.ResetFullPromoEmoteCooldown()

Musician.Utils.OverrideNextFullPromoEmote

Override the next full promo emote

Musician.Utils.OverrideNextFullPromoEmote()

Musician.Utils.SendPromoEmote

Send the "Player is playing music" emote with promo message

Musician.Utils.SendPromoEmote()

Musician.Utils.GetVersionText

Return the current version as text for the end user

version = Musician.Utils.GetVersionText()

Returns

  • version (string)

Musician.Utils.VersionCompare

Compare two version numbers

difference = Musician.Utils.VersionCompare(versionA, versionB)

Arguments

  • versionA (string)
  • versionB (string)

Returns

  • difference (number) 0 if A = B, 1 if A > B, -1 if A < B

Musician.Utils.PaddingZeros

Add padding zeros

formattedNumber = Musician.Utils.PaddingZeros(number, zeros)

Arguments

  • number (int)
  • zeros (int)

Returns

  • formattedNumber (string)

Musician.Utils.FormatTime

Format time to mm:ss.ss format

formattedTime = Musician.Utils.FormatTime(time, simple)

Arguments

  • time (number)
  • simple (boolean)

Returns

  • formattedTime (string)

Musician.Utils.ParseTime

Parse time in seconds from mm:ss.ss format

seconds = Musician.Utils.ParseTime(timestamp)

Arguments

  • timestamp (string)

Returns

  • seconds (number)

Musician.Utils.ShallowCopy

Shallow copy a table

http://lua-users.org/wiki/CopyTable

copy = Musician.Utils.ShallowCopy(orig)

Arguments

  • orig (table)

Returns

  • copy (table)

Musician.Utils.DeepCopy

Deep copy a table

http://lua-users.org/wiki/CopyTable

copy = Musician.Utils.DeepCopy(orig)

Arguments

  • orig (table)

Returns

  • copy (table)

Musician.Utils.DeepMerge

Deep merge two tables

merged = Musician.Utils.DeepMerge(merged, orig)

Arguments

  • merged (table)
  • orig (table)

Returns

  • merged (table)

Musician.Utils.FlipTable

Flip a table

flipped = Musician.Utils.FlipTable(orig)

Arguments

  • orig (table)

Returns

  • flipped (table)

Musician.Utils.GetOs

Return operating system name

os = Musician.Utils.GetOs()

Returns

  • os (string)

Musician.Utils.EasyMenu

Blizzard's EasyMenu using MSA_DropDownMenu

Musician.Utils.EasyMenu()

Musician.Utils.EasyMenu_Initialize

Blizzard's EasyMenu_Initialize using MSA_DropDownMenu

Musician.Utils.EasyMenu_Initialize()

Musician.Utils.SetFontStringTextFixedSize

Set text to a FontString element ensuring the visual text size is respected

Musician.Utils.SetFontStringTextFixedSize(fontString, text)

Arguments

  • fontString (FontString)
  • text (string)

Musician.Utils.GetByteReader

Return byte reader functions for provided data string

readBytes = Musician.Utils.GetByteReader(data, err)

Arguments

  • data (string)
  • err (string) Error to be returned in case of reading error

Returns

  • readBytes (function) , getCursor (function)

Musician.Utils.ForEach

Call function for each item of the provided table

Musician.Utils.ForEach(list, func)

Arguments

  • list (table)
  • func (function) Takes 3 arguments: value, key and the provided table.

Musician.Utils.GetRandomArgument

Randomly returns one of the provided arguments

Musician.Utils.GetRandomArgument()

Table of contents

Discord / MusicianList / Patreon / Donate

Clone this wiki locally