Add details and example usages of `obj.getVar()` etc.

[Benjamin-Dobell]

A common question on Discord is how to use getVar(), which is a solid indication the documentation isn't sufficient.

We should document how the variables must be global within the object, and that to retrieve variables from the object you must first get a reference to that object with getObjectFromGUID(), then call getVar() on that.

Should probably expand upon:

• getTable
• getVar
• setTable
• setVar

Also, the docs for getVar should be updated to reflect the fact it does work for tables. Not only does it work just fine for tables, it works for tables containing functions, and userdata etc. You can call functions from other scripts, call functions on the userdata etc. it all works just fine! Instead, getTable really just means copy table! EDIT: See comment below. There are subtle caveats.

[Benjamin-Dobell]

Global

function onLoad()
    local obj = getObjectFromGUID('5fab3a')

    -- local globalTable = obj.getVar('GLOBAL_TABLE')
    globalTable = obj.getVar('GLOBAL_TABLE')

    log(globalTable)
end

Object script

GLOBAL_TABLE = {
    nested_array = {
        1,
        2,
        3
    }
}

Well, there you go, I just learnt something new. getVar() works flawlessly as long as you only store references in upvalues local. If you try store them in a global you get:

Attempt to perform operations with resources owned by different scripts.

What's really interesting here is that if you do use upvalues, you can even a hold of references to variables that would normally have been garbage collected from another script.

e.g. If you modify the script above to in Global's onLoad grab onto nested_array, then (using Wait) in the object's script set GLOBAL_TABLE to a different variable (GLOBAL_TABLE = {}), the object's Lua context is no longer hanging onto nested_array. However, you can still interact with it in Global just fine.