How to use Twine/Tweecode Variables and Macros from Custom Macro

This tutorial is aimed at people wanting to use JavaScript in their Twine stories. This is advanced topic and is not necessary for writing most stories. Twine's ease in integrating JavaScript was a key factor when I was evaluating interaction fiction systems. Please read the tutorial on creating a custom macro in Twine first.

Twine/Tweecode has the ability to use macros and variables. In the Responsive, Sugarcane and Jonah StoryFormats macros and variables are stored in a place where they are accessible by custom macros for both reading and writing.

All custom macros are stored in a global object called "macros". They can be referred to by name. The actual macro code is in the "handler" property.

macros["custommacro"].handler(place, macroName, params, parser);
macros["display"].handler(place, "display", [ "SomePassage" ], parser);

In most cases it is sufficient to pass the place and parser arguments given to your custom macro into the macro you are calling.

Now, onto Tweecode variables. In tweecode variables are prefixed with a dollar sign so that the parser knows to lookup the variablename.

<<set $variablename = 1>><<print $variablename>>
<<if $variablename eq 1>>Success<<endif>>

Tweecode stores variables in the JavaScript object: state.history[0].variables. They are stored without the $ dollar sign "sigil".

state.history[0].variables["customvariables"] = 1;
if(state.history[0].variables["customvariables"] == 1) { 
  //... 
}

Knowing how to reuse Twine's macros and working with variables set in Tweecode from within JavaScript custom macros (and vice versa) opens many possibilities.