Are handles supported for strings in BGT? It's kinda weird about handles for things like vectors.
@1: Handles make more sense if you have experience with C / C++ / C#. Except they do some confusing things at times, even then, compared to their low-level counterparts. Handles are kinda like pointers, which are references to the memory address where the variable in question is stored. At the lowest level, you're dealing with how things are handled in the CPU and RAM, except CPUs, afaik, don't have a way to deal with object-oriented programming on a hardware level, and what's being passed around are values in CPU registers. Unless they're wrapped in a high-level construct, arrays are basically a pointer to the first entry, and saying x[y] is equivalent to a pointer to x+(y×sizeof(&x)).
Naturally, that can get messy real quick with complex programs, and Java simplifies it by making everything function as a handle/pointer/reference. This means you need methods for cloning objects (ex: System.arraycopy), which normally isn't that big a deal. For some reason, Angelscript (in which BGT is built) goes with something in between but closer to C#.
So anything done in BGT without an @ is trying to act on the data directly. To make matters more confusing, if you call a function like myfunc(x), it works regardless of whether the function takes a handle or its referent.
Generally speaking, if you want it to work the way it does in Java, you'll be using lots of @s. And that's usually what you want.
BGT doesn't let @ work on ints, floats, etc, which I believe is how it works in Java, too? But if you declare a function or method that takes "int &out" instead of just "int", that's effectively the same as sending a reference rather than a copy. ... But you don't do anything different when modifying the variable, because that would make sense -_-

Generally, you want to use handles in these situations:

• Comparing class instances. If (@a == @b), if (@x == @this). This is the same as Java if (a == b) and if (x == this).

• When a function or method needs to permanently modify the objects passed to it. If you wanted to write an implementation of quicksort in BGT, for instance, your parameters would be declared as int[]@, rather than just int[]. Same holds if it's a different type of array.

• Assigning. "@a = b" makes it so that a and b reference the same instance. "a = b" attempts to clone b to a, which will usually break on an already-initialized object without an opAssign method. You're probably wondering why it's "@a = b", and not "@a = @b", and I have no idea.

• Dictionaries. BGT is sufficiently weird about this that I try to always have functions to simplify it. If you want to add a sound to a dictionary, you'd do something like "dict.add(key, @handle)", and to get something from a dictionary, you need to have a handle to assign it to: "dict.get(key, @handle)".

• Factory functions should generally return handles. "sound@ get_sound(string filename)", for instance.

• Object arrays, especially as members of another class. This shows up a lot in games (ex, a class for a map, level, etc, with an array of items or enemies). "enemy@[] enemies". This gets confusing, because you can say "enemy@[]", "enemy[]@", "enemy@[]@", or "enemy[]", and they all mean slightly different things. If the @ is after the brackets, it's a handle to the array. If it's before the brackets, it's an array of handles. I generally use arrays of handles more than handles to arrays, and handles to arrays of handles is probably useful but hasn't come up much.

• Remember that null is already treated like a handle, so you should never say "@null", but should always say "@a = null" when nullifying a reference. I think "a=null" would cause a null pointer error.

As a general rule, when in doubt, use handles. Also, order of operations can be a jerk and require you use parentheses to avoid ambiguity regarding to what the @ refers, but I haven't worked out the exact order and just use parentheses for anything with a dot or brackets, just to be safe.

Another thing to consider when using pass by value and pass by reference, is that of the nature of the call. Note: all code is in c++. I do not know bgt. I'm assuming that bgt has some equivalent as it is a distant derivative of C, but so apply this to bgt with a bit of salt.

slow and unsafe.
This is equivalent to a normal function call where all of the arguments passed into the function are copied. Any changes made to those variables are not reflected in the variables of the calling function.

#include <iostream>
using namespace std;

void variableTest(int x, int y);

int main()
{
    int x = 1;
    int y = 2;

cout << x << ", " << y << endl;

    variableTest(x, y);

cout << x << ", " << y << endl;

    return 0;
}

int variableTest(int x, int y)
{
    x += y;
    y -= x;

cout << x << ", " << y << endl;
}

slow and safe.
This is adding a const qualifier to the variables you pass into the function. This is basically not use and virtually pointless because if you already are passing by value, the changes you make will not effect the original values. If you want the variables to be read-only however, be my guest.
The following code probably wont work, as i'm trying to modify a constant variable, but that could be useful though if you were trying to minimize access and keeping grubby little fingers where they don't belong.

#include <iostream>
using namespace std;

void variableTest(const int x, const int y);

int main()
{
    int x = 1;
    int y = 2;

cout << x << ", " << y << endl;

    variableTest(x, y);

cout << x << ", " << y << endl;

    return 0;
}

int variableTest(const int x, const int y)
{
    x += y;
    y -= x;

cout << x << ", " << y << endl;
}

fast and unsafe
This is the most dangerous of the 4 options. If you pass by reference, the function can modify anything it wants to as it pertains to your variables. It is fast though. A pass by reference is basically pass by pointer. It copies 4 or 8 bytes (the size of a memory address depending on your operating system) instead of passing the class instance or object you have defined that is a  dozen or more bytes. copying dozens and dozens of bytes just to make a function call will slow your program down to a crawl.

#include <iostream>
using namespace std;

void variableTest(int & x, int & y);

int main()
{
    int x = 1;
    int y = 2;

cout << x << ", " << y << endl;

    variableTest(x, y);

cout << x << ", " << y << endl;

    return 0;
}

int variableTest(int ^ x, int ^ y)
{
    x += y;
    y -= x;

cout << x << ", " << y << endl;
}

fast and safe.
The best of both worlds fast and safe is pass by constant reference. If you are still with me you can probably guess what this means. We get the speed and efficiency of pass by reference, but the function can not modify the variables. This is especially useful for operating system / API calls where you are getting data from the user or application program. You as the system level software or operating system have no right to modify the data you've been given. plus if they have given you a struct of of employee data that has several variables like name, id, and address, you would much rather be shuffling around pointers and not big bulky employee structs.

#include <iostream>
using namespace std;

void variableTest(const int x, const int y);

int main()
{
    int x = 1;
    int y = 2;

cout << x << ", " << y << endl;

    variableTest(x, y);

cout << x << ", " << y << endl;

    return 0;
}

int variableTest(const int x, const int y)
{
    x += y;
    y -= x;

cout << x << ", " << y << endl;
}