So I'm reading through the macro library which is excellently documented here:
http://www.motoslave.net/sugarcube/1/docs/macros.html
But I can't figure out what the practical difference is between <<choice>>, <<actions>>, and <<link>>?
When I use their examples in a test environment, they all seem to have the same effect (open a new passage).
Can someone shed some light on this?
Comments
(note: because this is about Twine 1 and to save space, I am going to use Twee notation in my examples. A line starting with a double colon :: indicates a new passage, the text on the same line as the double colon is the new passage's title. All lines below the double colon is the new passages contents until you reach either another double colon or the end of the example.)
1. <<actions>>
As stated by the documentation this macro shows a set of links in a passage only once, so if you navigate forward to that same passage again the links will not show a second time.
eg. If you move forward from Start to Passage 1 then to Passage 2 via either of the Options and final move forward to Passage 1 again you will not see the Options the second time.
2. <<choice>>
This works very similar to <<actions>> except that when you finally move forward to Passage 1 again you will see the Options but that will not be click-able.
The <<choice>> macro was original created for the Jonah story format which displays the next passage below the current one, so the macro allowed Author's to have a link type that forced a Reader to make a choice that they could not undo. I believe it was added to SugarCube for compatibility reasons.
3. <<link>>
As stated by the documentation this link type allows the Author to control exactly which feature of the above two link types they want to use and it also has the functionality of a markup link. This means that an Author could in theory replace all other link types in their code with this one and do everything.
The <<actions>> macro displays each of the links you give it in a list. Each of the links may be used only once, after which it is removed from the list. You should only have one of these within a passage.
The <<choice>> macro disables (the link text is left behind) all other <<choice>> macro managed links within the same passage. You may have one or more of these within a passage.
The <<link>> macro allows disabling or removing the given link, so it doesn't really offer much that <<actions>> and <<choice>> do not already. It's largely a legacy holdover from when you couldn't use $variables within link markup (and because of that, I'm probably going to change what it does in SugarCube 2.x).
If you're looking for a link which does something other than navigating to a passage, then you probably want to look at the <<click>> macro.