The two ref commands (*gotoref and *setref) are advanced ChoiceScript commands that allow further reference of variables by their names and values.
They are essentially extensions of the *set and *goto commands. They perform exactly the same operations, but have a little bit more flexibility when it comes to referral.
With *goto, for example, you must refer to an existing label by its raw name. With *gotoref you could get a label's name from a value stored within a string variable. Similarly with *set, you must refer to an existing variable's name. *setref however, allows you to set a variable by reading the value of another.
Knowlege of the ref commands is not necessary in order to create a fun, high quality or successful game.
|
"They add complexity without adding much value." - Official CoG Tutorial |
|---|
They are by no means easy to use or understand and the rest of this article will assume you are relatively adept at programming or highly experienced in coding ChoiceScript. If you believe you are neither, we strongly recommend you stick to *goto and *set .
*Gotoref (Full Explanation)
To fully understand this section, you should already be well experienced in all the basic aspects of ChoiceScript, particularly labels and the *goto command.
The Basics
*gotoref is an extension of the *goto command and performs exactly the same function. The primary difference is how it allows you to refer to the name of the label you wish to jump to.
With *goto there is only one way in which you can refer to a label, and that is by its raw name, as a part of the command argument:
*goto text *label ignored The text here will not be displayed as the goto above will jump to the label beneath it. *label text This text will be displayed!
*gotoref however gives you a little more flexibility. While we must still pass the name of a label in the argument, we can now do it in one of two ways:
- Just like with *goto, we can pass the name of the label as it is.
- Or we can pass the name of a variable containing the name of our label.
By default, *gotoref will attempt to use the latter method to retrieve the name of a label, like so:
*temp text *set text "display" *gotoref text *label text This text will not be displayed, as we're using the variable value method. *label display This text WILL be displayed as "display" is the VALUE of the variable 'text'
This can be quite hard to wrap your head round. So think of it like this; *goto text will tell the game to look for a label called "text" but *gotoref text will tell it to look inside the variable called "text" for the name of the variable you wish to jump to.
So if we changed *set text "display" to *set text "next" the game would try to jump to *label next. Likewise if we set the value of the variable text to "text" then it would jump to the label text.
To use the *gotoref as if it were merely *goto, you simply wrap quotation marks around the argument (this tells it that it's a string value not a variable) - although, in reality it's probably easier to just remove ref from the end of the command (and use *goto without the quotation marks).
*gotoref "text" *label text This text will be displayed, as *gotoref is taking the value "text" as the given label. *finish *label display This text WILL not display as a *finish command ends the scene above.
Examples
The following section provides some basic examples of *gotoref usage in ChoiceScript scenes - there is some documentation. All examples should work if copy and pasted into your own vignettes/scenes - so feel free to use and/or modify them.
In the following example the player is prompted to enter the text "red" or "blue" - this is set as the value of the variable chosenlabel which we pass as our argument in our *gotoref line. This means that we're telling the game to jump to the label that matches the value of chosenlabel. So in effect, whatever the player enters in that textbox is what the game will attempt to jump to. If he enters "red", we'll jump to *label red. If he enters "blue" we'll jump to *label blue. If he enters anything else, say "green", again our game will attempt to jump to *label green (although in this case, that will cause an error, as it doesn't exist!)
*temp chosenlabel Please enter either red or blue. *input_text chosenlabel *gotoref chosenlabel *label red You chose red! *finish *label blue You chose blue! *finish
While again, somewhat of a flawed example - the following demonstration shows how you can make the setting of a variable based on a choice and use the same line *gotoref choice to send you to the appropriate label, based on its value. Strictly speaking it would be much easier to just write 'You chose rock!' underneath our choices, which is exactly what the quote "They add complexity without adding much value." is referring to.
*temp choice Rock, paper or scissors? *Choice #Rock! *set choice "rock" *gotoref choice #Paper! *set choice "paper" *gotoref choice #Scissors! *set choice "scissors" *gotoref choice *label rock You chose rock! *finish *label paper You chose paper! *finish *label scissors You chose scissors! *finish
*Setref (Full Explanation)
To fully understand this section, you should already be well experienced with all basic aspects of ChoiceScript, particularly variable types and the *set command.
The Basics
*setref is an extension of the *set command and performs exactly the same function (the setting of variables). The primary difference is how it allows you to refer to the name of the variable you wish to set.
With *set there is only one way in which you can refer to a variable, and that is by its raw name:
*set text "This is text!" *comment the variable text will be set as "This is text!"
*gotoref however gives you a little more flexibility. While we must still pass the name of a label in the argument, we can now do it in one of two ways:
- Just like with *set, we can refer to the name directly.
- Or we can pass the name of a variable containing the name of our desired variable.
By default, *setref will attempt to use the latter method to retrieve the name of a variable.
*temp text *set text "Hello" *setref text "This is text!"
The above example will cause an error because of this. Much like *gotoref, *setref uses the value of the variable, not the variable itself, as the argument name of the variable to be set.
So in effect, the above example is trying to set a variable called "Hello" to the value "This is text!" - because Hello is the current value of the variable we used in the *setref argument.
Just as with *gotoref we can enclose our argument in quotation marks to refer to it by its name, instead of its value. Although again, you may as well just use the original *set for that kind of behaviour.
*temp text
*set text "Hello"
*setref "text" "This is text!"
${text}
*comment ${text} will print "This is text!"
Examples
The following section provides some basic examples of *setref usage in ChoiceScript scenes - there is no documentation. All examples should work if copy and pasted into your own vignettes/scenes - so feel free to use and/or modify them.
Simple system that allows you to add or subtract a single stockpile of goldcoins between three different containers, making some use of the setref command to make more dynamic code*.
*You'd only need to change the *sets under the first choice (and the variable names) to change the system, rather than the several tens of ifs and normal sets, you might otherwise have.
*temp containerA
*set containerA 0
*temp containerB
*set containerB 0
*temp containerC
*set containerC 0
*temp currentContainer
*temp goldcoins
*set goldcoins 10
*temp n
*temp text
*label selectcontainer
Choose a container!
*choice
#Select Container A
*set currentContainer "containerA"
*goto dowhat
#Select Container B
*set currentContainer "containerB"
*goto dowhat
#Select Container C
*set currentContainer "containerC"
*goto dowhat
*label dowhat
Would you like to add or subtract gold from ${currentContainer}?
*set n {currentContainer}
It currently contains: ${n} gold coins
*set n 0
*choice
#Add
*goto addstuff
#Subtract
*goto subtractstuff
*label addstuff
You currently have ${goldcoins} goldcoins
*if (goldcoins = 0)
*line_break
You don't have any coins left to put in ${currentContainer}!
*goto error
*input_number n 1 goldcoins
*setref currentContainer ({currentContainer} + n)
*set goldcoins (goldcoins - n)
*goto currentstats
*label subtractstuff
*set n {currentContainer}
This container currently contains: ${n} gold coins
*set n 0
*if ({currentContainer} = 0)
*line_break
There are no coins to subtract in ${currentContainer}!
*goto error
*input_number n 1 {currentContainer}
*setref currentContainer ({currentContainer} - n)
*set goldcoins (goldcoins + n)
*goto currentstats
*label error
*line_break
Please try again...
*line_break
*goto selectcontainer
*label currentstats
Gold coins in containerA: ${containerA}
*line_break
Gold coins in containerB: ${containerB}
*line_break
Gold coins in containerC: ${containerC}
*line_break
Gold coins in Gold Coins: ${goldcoins}
*page_break
*goto selectcontainer
- Reflect: How could you improve this system's flexibility/dynamics?