Docs
  • 🍎Stream Avatars
    • Introduction
    • ⏩Quick Setup
    • 📸How to Overlay
      • OBS
      • Streamlabs Desktop
      • XSplit
      • Twitch Studio
      • Unlisted / Other
    • ⚛️Extension
    • ⏩Quick Guide
    • 📬Commands
      • ❗!commands
      • ↕️Selection Commands
        • !random
          • !mass random
          • !change {user} {command} random
        • !avatars
          • !avatar {avatar}
          • !change {user} !avatar {avatar}
          • !change {user} !avatar {avatar} {timer}
          • !mass avatar {avatar}
          • !mass avatar {avatar} {timer}
        • !color
        • !gear
        • !nametags
        • !actions
        • !show
      • ↕️Minigames and Fun Commands
        • !basketball
        • !battleroyale
        • !boss
        • !duel {user} {amount}
        • !slots {amount}
        • !bomb {user}
        • !sling {power} {angle}
        • !fart
        • !quote {#}
        • !roll {#d#}
        • !8ball {question}
        • !freeze {user} {seconds}
        • !pin {user} {x%} {y%} {seconds}
        • !attack {user}
        • !dance
        • !hug {user}
        • !throw
        • !explode {target}
        • !bet {amount} {calltype}
        • !scale {target} {size}
        • !spawn game
        • !screensaver {seconds}
        • ↕️!mass {command}
      • ↕️Shop Commands
        • !shop
        • !buy avatars
        • !buy colors
        • !buy gear
        • !buy nametags
        • !buy actions
      • ↕️Currency Commands
        • !currency
        • !currency add {user} {amount}
        • !currency remove {user} {amount}
        • !currency give {user} {amount}
      • ↕️Gifting Commands
        • !gift {user} lootbox {name}
        • !gift {user} avatar {avatar}
        • !gift {user} gear {gear_set} {gear_piece}
        • !gift {user} color {avatar} {color}
        • !gift {user} nametag {nametag}
        • !gift {user} all true
        • !currency add {user} {amount}
      • ↕️Remove Ownership Commands
        • !remove {user} avatar {avatar}
        • !remove {user} gear {gear_set} {gear_piece}
        • !remove {user} color {avatar} {color}
        • !remove {user} nametag {nametag}
        • !currency remove {user} {amount}
      • !extension
      • !hideavatar
      • !mass {command}
      • !change {user} {command}
      • !spawn {title}
      • !whitelist add {user}
      • !blacklist add {user}
      • !mod add {user}
      • !leaderboard
      • !leaderboard exclude {user}
      • !game exclude {user}
      • !sounds
      • !shoutout {user}
    • 📃Application Settings
      • General
      • Login Details
      • Minigames
      • Avatars And Gear
      • Sounds
      • Nametag Settings
      • Import & Export
      • Shop Editing
      • User Editing
      • ❗Unfinished Docs!
      • ❗Bot Commands
        • ❗Custom Commands
      • ❗Edit Lootboxes
      • ❗Backgrounds
      • ❗Bot Commands
    • 🎨Content Creating
      • Creating Avatars
      • Extension Sorting Order
      • Deleting Avatars, Palettes/Colors, and Gear
      • Creating Gear
      • Creating Colors
      • Creating Backgrounds
      • Creating Bosses
      • Creating Player Classes (boss)
      • Creating Nametags
      • Creating Lootboxes
      • Importing Scripts
      • Importing Private Content
      • Creating Custom Redemptions
      • Creating Extension Thumbnails
      • Creating Custom Language Localization
    • 💫Integrations
      • Stream Deck
    • ❓Support
      • New Platform Additions
      • Various Troubleshooting
      • Data Folder
      • Beta Branch
      • F.A.Q
      • Crash Log - Event Viewer
    • 🤝Stream Avatars Partner
  • ⚙️LUA Scripting API
    • Introduction
    • Quick Start
    • API Reference & Tips
      • 🌎Global Functions
        • log
        • wait
        • yield
        • yieldBreak
        • async functions
        • waitForAsync function
        • stopAsync function
        • get
        • set
        • applyImage
        • waitForAnimation
        • webrequest get/post
        • getUser
        • getUsers
        • getUserById
        • getCurrency
        • addCurrency
        • removeCurrency
        • adjustCurrency
        • getBackground
        • getScriptableBlocks
        • getAvatar
        • getAllAvatars
        • runCommand
        • writeChat
        • setProperty
        • getApp
        • save
        • load
        • addEvent
        • removeEvent
        • keepAlive
      • 🔫Events
        • BankController
        • ServiceController
        • Read Chat
        • Websockets
        • Scriptable Block Trigger
        • Platform Donation
        • App State Change
        • Custom Command
        • Basketball Outcome
        • BattleRoyale Outcome
        • Boss Battle Outcome
        • Boss Battle Player Joined
        • Duel Outcome
        • On JumpCatch Star
        • On Background Switch
        • On Avatar Change
        • On New Viewer
        • On InitializeNewViewer
        • On Follower
        • On Raid
        • On Subscriber
        • On Avatar Spawn
        • On Trigger Object
        • On Hotkey
        • On Purchase
      • 📦Classes
        • App
          • globalAvatarScale {get;set}
          • globalNametagScale {get;set}
          • globalChatBubbleScale {get;set}
          • globalNametagStack {get;set}
          • getResolution
          • platformServiceSettings
          • setResolution
          • setFullscreen
          • getStreamer
          • convertPositionToPercent
          • convertPercentToPosition
          • playSound
          • createBomb
          • pitchSound
          • stopSound
          • soundIsPlaying
          • createGameObject
          • getGameObject
          • createChatBubble
          • createWebsocket
          • removeWebsocket
          • sendWebsocketMessage
          • getAppState
          • sha256_base64
          • getUserFromData
          • getIdsFromData
          • deleteUser
          • exportAvatarImage
          • translateCommand
        • User
          • id {get}
          • isActive {get}
          • isFake {get}
          • lastActiveDate {get}
          • secondsSinceLastActive {get}
          • displayName {get}
          • channelName {get}
          • follower {get}
          • vip {get}
          • subscriber {get}
          • moderator {get}
          • platformModerator {get}
          • platform {get}
          • streamer {get}
          • avatar {get;set}
          • scale {get;set}
          • override_scale {get;set}
          • color {get;set}
          • nametag {get;set}
          • getState
          • getGear
          • setGear
          • setPosition
          • getPosition
          • getWearableAvatars
          • getWearableAvatarColors
          • getWearableGearSetPieces
          • getWearableNametags
          • setTemporaryAvatar
          • setTemporaryColor
          • setTemporaryNametag
          • setTemporaryGear
          • setTemporaryNone
          • clearAllTemporarySelections
          • chatBubble
          • runCommand
          • physics
          • saveUserData
          • loadUserData
        • Physics
          • grounded {get;set}
          • setVelocity
        • ObjectPhysics
          • hasTrigger {get}
          • hasRigidBody {get}
          • layer {get;set}
          • kinemetic {get;set}
          • setVelocity
          • addBoxCollider
          • addCircleCollider
          • addBoxTrigger
          • addCircleTrigger
        • Avatar
          • name {get}
          • getGear
          • getGearPieces
          • getColors
          • getActions
        • GameObject
          • image {get}
          • destroy
          • setAngle
          • setPosition
          • getPosition
          • adjustPosition
          • getScale
          • setScale
          • adjustScale
          • physics
        • Image
          • playAnimation
          • stopAnimation
          • flipX
          • flipY
          • sorting
          • anchor
        • ScriptableBlock
          • id {get}
          • position
      • 📤Helper Class
        • createCooldown
        • checkCooldown
        • setCooldown
        • cooldownTimeLeft
        • startsWith
        • replace
        • split
        • randomElement
        • hasValue
        • matchRegex
Powered by GitBook
On this page
  • Do's and Don'ts
  • Pre-existing Functions and Data
  1. LUA Scripting API

API Reference & Tips

API - Reminders, Helpful tips, and things you should know before starting.

Press F5 to reload and replay scripts while Stream Avatars is connected!

To view the console log, focus Stream Avatars, and press Alt+C, then type: Lua After hitting enter, a console logger will come up showing you the logs. Once it is open, you can close the command input by pressing Alt+C again.

You can close the console log by repeating this process.

Do's and Don'ts

function anotherFunction()
    --see how this function is above the return function()?
    
    --the double dash is how we make line comments in lua scripting
    
    --[[
        this is how we make block comments in lua scripting.
        multiple lines. woooo
    ]]
    
    log('hello world');
end

return function()
    anotherFunction();
    --this should be the last function of your script! 
end --Don't put anything below the last end
return function()
    local test = 'hi';
    local test2 = false;
    
    if test2 == false and test == 'hi' then
        log('&& operators is just and');
    else if test2 == true or test == 'bye' then
        log('|| operators is just or');
    end
    
    if test2 == false then
        log('simple if');
    end
    
    if test2 == false then
        log('simple if else');
    else
        log('blah');
    end
end
return function()
    --in lua, all arrays start at index 1
    local test {'one', 'two', 'three' };
    log(test[1]); --this will print out one
    
    --notice #test is how we get the length of the array. which is 3.
    --a simple for loop
    for i = 1, #test do 
        log(i); --this will print out: 1, 2, 3
    end
    
    --a simple while loop
    local test = 0;
    while test < 5 do
        test = test + 1;
    end
    
    local a = { }
    a[1] = 'one';
    a[2] = 'two';
    a['hello'] = 'hello world';
    
    
    --ipairs is indexed --note hello world does not get printed
    for key, value in ipairs(a) do
        log(key .. value);
    end
    --1one
    --2two
   
    
     --pairs key order is unspecified and not garunteed.
    for key, value in pairs(a) do
        log(key .. value);
    end
    --1one
    --hello world
    --2two
end
return function()
    --how to concatenate strings in lua. 
    --(two periods is how you add strings together)
    log('this is how ' .. 'you combine strings');
end

coroutines are unique in SA Lua. They allow for scripts to wait for something to finish before continuing. Do not cross global variables between coroutines! This can be tricky to use but is very powerful for scripting sequences of events.

function exampleCoroutine()
    --code in this function does not have access to global scope variables
    --Do not reference myGlobalScopeVariable directly!
    
   
    local myVar = get('myGlobalScopeVariable'); 
     --grab the global var and make it local
    log(myVar); --prints hi
    
    myVar = 'bye';
    
    --set the global var to the local variable.
    set('myGlobalScopeVariable', myVar);
end

--this variable belongs to the main coroutine and nowhere else!
myGlobalScopeVariable = 'hi'; 
return function()
    wait(1); 
    --a really basic coroutine yield 
    --that waits 1 second before continuing.
    
    local coroutineId = async('exampleCoroutine');
    waitForAsync(coroutineId);
    
    log(myGlobalScopeVariable); 
    --this prints bye because we waited for it to be set.
    
    keepAlive(); 
    --Pauses this coroutine indefinitely, allowing the other coroutines to exist.
end

Pre-existing Functions and Data

With LUA scripting in stream avatars, there are some addons your your script behind the scenes that you should know about!

return function()
    local a = { someData = 'hi', otherData = { 1, 2, 3 }};
    --some data table...
    
    local makeItString = json.serialize(a);
    --convert a to a JSON string
    
    log(makeItString);
    --prints the data structure.
    
    local b = json.parse(makeItString);
    --parse the string back into a table
    
    log(b['someData']); --prints hi
    
    
    --DO NOT TRY TO SERIALIZE NON-ARRAYS ALONG SIDE OF ARRAYS!
    local h = { };
    h[1] = 'hey'; --h is array
    h[2] = 'dont'; --h is array
    h['example'] = 'do'; --h is not array
    h['example2'] = 'this'; --h is not array
    local j = json.serialize(h); --stop! this breaks.
    
    --instead option 1:
    local k = { };
    k[1] = 'hey'; --k is array
    k[2] = 'DO'; --k is array
    k[3] = { }; --k is array
    k[3]['example'] = 'do'; --k is array
    k[3]['example2'] = 'this'; --k is array
    local l = json.serialize(k); --works
    
    --instead option 2:
    local m = { };
    m['n'] = { };
    
    m['n'][1] = 'hey';  --m is not array
    m['n'][2] = 'DO';  --m is not array
    m['example'] = 'do'; --m is not array
    m['example2'] = 'this'; --m is not array
    local o = json.serialize(m); --works
    
    
    
end

Only exists when the custom command is set to Run As: On Command Call

commandUser is the user that issued the command causing this script to run.

commandMessage is the message that was sent to issue the command.

return function()
    --this script is ran by someone running the command...
    log(commandUser.displayName);
    log(commandMessage); --prints the full message of the command
    --if the custom command is set to "exact match = false", 
    --the commandMessage could be more than just the commandName
    
    --example:
    --commandMessage could be: !steal clonzeh
    --where the command is actually !steal
    --but since it doesn't have to match exactly, users can add info after it
end
--Scripts are able to control it's own trigger type with a setting. 
--(this makes it easier to share commands and keep their settings)

script_trigger_type = 'On Connect'; 
--with this line uncommented, the script will be forced to run as OnConnect


--with this line uncommented, the script will be forced to run as OnCommand
--script_trigger_type = 'On Command';

return function()
    log('script was triggered! the trigger type is: ' .. script_trigger_type);
end
PreviousQuick StartNextGlobal Functions

Last updated 1 year ago

⚙️
User
example !steal settings