Add-ons / <<replacelink>> Macro Set

Overview

SugarCube is a free (gratis and libre) story format for Twine/Twee, based on TiddlyWiki.

The macros included within this set are based upon the Combined Replace Macro Set (v1.1.7) by Leon Arnott <l_1_l_0@yahoo.com>.

This package contains a SugarCube compatible version of the Combined Replace Macro Set. It is intended for use with SugarCube and will not work with other story formats (see the link above for the non-SugarCube version).

📝 Note: All responsibility for this version of the macro set falls upon me (Thomas M. Edwards <tmedwards@motoslave.net>). Please, do not bother Leon if you have issues with it. Address all issues to me, if it turns out to be problem with the base macro set, and not my modifications, then I'll let Leon know about it.

Requirements

This package requires SugarCube v2.0.0 or greater.

Contents

The files included in this package are:

• README.html: This document.
• replacelink-macro-set.min.js: The, minified, macros.
• replacelink-macro-set.css: The styles required by the macros.

Installation

JavaScript

1. Open the replacelink-macro-set.min.js file in a text editor (not a word processor) and copy its contents.
2. Paste them into your project's script section:
   • Twine 1: script-tagged passage.
   • Twine 2: Story JavaScript.

Stylesheet

1. Open the replacelink-macro-set.css file in a text editor (not a word processor) and copy its contents.
2. Paste them into your project's stylesheet section:
   • Twine 1: stylesheet-tagged passage.
   • Twine 2: Story Stylesheet.

Macros

<<insertlink>>

<<timedinsert>>

<<insertion>>

<<later>>

<<keyinsert>>

<<replacelink>>

<<timedreplace>>

<<mousereplace>>

<<hoverreplace>>

<<revision>>

<<keyreplace>>

<<timedremove>>

<<mouseremove>>

<<hoverremove>>

<<removal>>

<<once>>

<<keyremove>>

<<continuelink>>

<<timedcontinue>>

<<mousecontinue>>

<<keycontinue>>

<<cycle>>

<<mousecycle>>

<<timedcycle>>

<<keycycle>>

<<becomes>>

Notes

A warning about <<hoverreplace>>

As noted by Leon in the v1.1.5 update post, :

One thing that is still not yet fixed is the problem caused when the initial state is larger than the end state. Consider this code:

<<hoverreplace>>[img[large image]]<<gains>>Small text<<endhoverreplace>>

This code is still buggy because as soon as you mouseover the large image, it disappears, leaving the small text behind, and thus your pointer is no longer "over" the hoverreplace structure. I may still be able to fix this in the future, but generally, in this particular situation you should resort to <<mousereplace>>.

SugarCube notes

⚠️ Warning: When passing an optional $variable to the macros which can receive one, you must quote the $variable name (i.e. instead of $variable, use "$variable"). This is required because all macros in SugarCube get $variable substitution automatically, unlike the vanilla story formats where each macro has to perform $variable substitution itself. So, if you don't quote the $variable name, the macro will receive its value instead of its name.

In addition to the internal changes required to make the macro set fully work in SugarCube, additional changes include:

• All error messages now include the name of the macro issuing the error.
• The internal link class follows SugarCube standards (i.e. link-internal instead of internalLink). All other generated classes are untouched.
• All container macros adhere to the SugarCube standard of supporting both slash- and end-style closing tags (e.g. <</…>> and <<end…>>).
• Due to naming conflicts with some of SugarCube's own macros, and after discussion with Leon, some of the set's macros have been renamed:

Old Name	New Name
<<continue>>	<<continuelink>>
<<insert>>	<<insertlink>>
<<randomise>>	<<randomiselink>>
<<randomize>>	<<randomizelink>>
<<replace>>	<<replacelink>>
<<revert>>	<<revertlink>>
<<revise>>	<<reviselink>>

As a minor side benefit of this, these macros are now named consistently with the <<cyclinglink>> macro.

Live demo

Demo Twee code:

:: Start
Replace <<replacelink>>this text<<becomes>>this other text<<becomes>>is over<</replacelink>>. <<hoverreplace>>Hover here!<<becomes>>@@color:red;Hover red!@@<</hoverreplace>>