Variables declared three times?

[+Hügh]

I am currently working on writing a Wherigo cartridge by hand. With very little documentation out there, I find that the best way to do this is to study the Lua source code that has been generated by existing builders (Groundspeak, Wherigo\\Kit, Earwigo, etc).

 

I can't help but notice that variables are often declared three times over: once in-line, once in the cartridge.ZVariables table as a name-value pair, and once in the buildervar table as a table describing the type, name, and value of a variable.

-- in-line variable declaration
var_name = "var_value"
current_score = 3

-- variable declaration in the ZVariables table
cartridge.ZVariables = {
    var_name = "var_value",
    current_score = 3
}

-- variable declaration in the buildervar table
buildervar = {
    var_name = {
        Id = "00000000-0000-0bad-c0d3-000000000000",
        Type = "String",
        Name = "var_name",
        Value = "var_value",
        Description = "Description of variable var_name"
    },
    current_score = {
        Id = "00000000-0000-0bad-c0d3-000000000001",
        Type = "Number",
        Name = "current_score",
        Value = "3",
        Description = "Description of variable current_score"
    }
}

Why? Why is each variable declared three times? Does each declaration serve a different purpose, and, if so, what purpose does each declaration serve? Please explain, before I go absolutely crazy and smash my computer because nothing. makes. sense. Programming a Wherigo isn't like programming anything I've ever programmed before.  

 

Addendum: I did do a little research: it seems to me as if the cartridge.ZVariables table is somehow used to help the Wherigo player save cartridges, but I am not sure. I could not find any information on how the buildervar table is used, but I assume that it is somehow used to help Wherigo builders parse Lua code -- does this mean that I can omit the buildervar table in my code because I am not using a builder?  

Edited September 8, 2019 by Hügh
minor edits to improve question

[+Kalkendotters]

You are correct in your addendum:

var_name are normal LUA variables and have to be set and restored by the programmer.

ZVariables.var_name are part of a special object that will be automatically saved and restored by the Wherigo system

buildervar.var_name are helpobjects to remember what the user defined for the var in the builder. (not all builders use this system)

 

So, if you don't need persisent variables for save/load you can use var_name.  If you want your values to be remembered during a save/load, you have to add them to the object ZVariables.

[+Hügh]

5 hours ago, Kalkendotters said:

You are correct in your addendum:

var_name are normal LUA variables and have to be set and restored by the programmer.

ZVariables.var_name are part of a special object that will be automatically saved and restored by the Wherigo system

buildervar.var_name are helpobjects to remember what the user defined for the var in the builder. (not all builders use this system)

 

So, if you don't need persisent variables for save/load you can use var_name.  If you want your values to be remembered during a save/load, you have to add them to the object ZVariables.

 

Thank you for your response, Kalkendotters. Follow up question: do I ever need to change/modify the values in the cartridge.ZVariables table if I change/modify the value of a variable? 

my_variable = "initial value"

cartridge = {
    my_variable = "initial value"
}

-- Say I need to change/modify the value of `my_variable` to "modified value". 

-- Should I do this?
my_variable = "modified value"

-- Or should I do this?
my_variable = "modified value"
cartridge.my_variable = "modified value"

Wherigo.Command("SaveClose")

* If it matters: I want to make sure that the "updated" value of "my_variable" gets saved when the player saves and reopens their cartridge.

Edited September 8, 2019 by Hügh
added code

[+Kalkendotters]

They are different variables, so it all depends on what you want to achieve.

If the value does not need to be remembered you can use the 'simple' version.

If it has to be remembered, you have to use the cartridge-object. But you can use it direct (with some extra runtime overhead) so no need to copy it to a local var. So you can just do:

cartridge = {
    my_variable = "initial value"
}

//

cartridge.my_variable = "modified value"

Wherigo.Command("SaveClose")

 

If needed you can use the OnRestore method of the cartridge to Enable/Disable zones, Tasks etc, or set other variables

[+Hügh]

21 minutes ago, Kalkendotters said:

They are different variables, so it all depends on what you want to achieve.

If the value does not need to be remembered you can use the 'simple' version.

If it has to be remembered, you have to use the cartridge-object. But you can use it direct (with some extra runtime overhead) so no need to copy it to a local var. So you can just do:

cartridge = {
    my_variable = "initial value"
}

//

cartridge.my_variable = "modified value"

Wherigo.Command("SaveClose")

 

If needed you can use the OnRestore method of the cartridge to Enable/Disable zones, Tasks etc, or set other variables

 

Ah! I suppose I can just store all of my variables in the cartridge.ZVariables table. Thanks for your help!