ref_create

This function creates a reference to a Variable in a struct or instance.

You provide the struct or instance that the variable belongs to, or a reference to it, and the name of the variable (as a string), or reference to a variable that stores the name or index.

For Arrays, an index can be provided as the third argument that tells which index to create a reference to.

More complex references can be created. For the full list of possibilities, see the examples.

NOTE The value can be changed through the reference in The Debug Overlay.

WARNING You cannot create references to Local Variables, since they exist only temporarily and cannot be referenced.

Syntax:

ref_create(dbgrefOrStruct, dbgrefOrIndex[, index]);

Returns:

Reference

Example 1: Basic Reference to an Instance Variable

text = "This is some text";
ref_to_text = ref_create(self, "text");

The code above first creates an instance variable text in the Create event and then creates a reference to it using ref_create, that's stored in the variable ref_to_text.

Example 2: Basic Reference to an Array Index

array = [1, 2, 3, 4, 5];
ref_to_index = ref_create(self, "array", 2);

The code above first creates an array array with 5 elements in the instance executing the code. It then creates a reference to index 2 (the third element) using ref_create. The reference is stored in a new instance variable ref_to_index.

Example 3: Complex Reference

the_struct = {a: "text", b: 485};
ref_to_struct = ref_create(self, "the_struct");
ref_to_struct_var = ref_create(ref_to_struct, "a");

The above code first creates a struct the_struct in the instance executing the code that has two variables. It then creates a reference to that struct using ref_create that is then passed as the dbgrefOrStruct parameter to the next call to ref_create. This last call to ref_create creates a reference to the struct's variable a and stores it in a variable ref_to_struct_var. The struct itself is passed to the function indirectly, using the reference stored earlier in the variable ref_to_struct.

Example 4: Complex Array Reference

array = [3, 4, 1, 7, 8, 2];
index = 4;
ref_to_array = ref_create(self, "array");
ref_to_index = ref_create(self, "index");
ref_to_array_at_index = ref_create(ref_to_array, ref_to_index);

The above code creates a reference to an array array where both the first parameter to ref_create (the array to reference) and the second parameter (serving as the index into the array) are themselves references. This means that if you assign a different value to the variable index later on, the array element indexed by ref_to_array_at_index also changes to the new value set. If you assign an entirely new array to the instance variable array, ref_to_array_at_index will reference the element at the same index in that array.