v2.0.0

Finally...

.gitignore

@@ -45,3 +45,5 @@ $RECYCLE.BIN/
 Network Trash Folder
 Temporary Items
 .apdisk
+
+/old

LICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <http://unlicense.org/>

docs/event-macros.md

@@ -0,0 +1,74 @@
+## The Event Macros
+
+[Back to the main readme](https://github.com/ChapelR/custom-macros-for-sugarcube-2/blob/master/readme.md).
+
+This macro set allows Twine authors to create event programming without needing to use JavaScript or jQuery.
+
+**THE CODE:** [Minified](https://github.com/ChapelR/custom-macros-for-sugarcube-2/blob/master/scripts/minified/events.min.js). [Pretty](https://github.com/ChapelR/custom-macros-for-sugarcube-2/blob/master/scripts/events.js).  
+**DEMO:** [Available](http://holylandgame.com/custom-macros.html).  
+**GUIDE:** Not available.
+
+### Macro: `<<event>>`
+
+**Syntax**:
+```
+<<event type [selector]>>
+    ...
+	<<which keycode>>
+	    ...
+	<<which keycode>>
+	    ...
+<</event>>
+```
+
+This macro set can be used to add more interaction to your game; things like keyboard hotkeys, controls, clickable non-link elements, and more.  Once registered, events are essentially permanent (though they can be removed via JavaScript and suppressed via code logic); therefore, the best place to create events is your StoryInit special passage.  Note that the element the event is tied to does not need to be rendered (or currently on the page or in the passage) in order to attach an event to it.
+
+* **type**: a valid jQuery event type.  Some events that may be of interest:
+  * `click`: fires when an element is clicked on.
+  * `dblclick`: fires when an element is double-clicked on.
+  * `keyup`: fires when an key is pressed and released.
+  * `keydown`: fires immediately when a key is pressed.
+  * `mouseup`: fires when a mouse button is pressed and released.
+  * `mousedown`: fires when a mouse button is pressed.
+* **selector**: (optional) a valid jQuery/CSS selector.  with some events (such as key presses), this checks for focus; with others it checks for the target element of the event (such as mouse clicks).  if no selector is provided, the event is bound to the document element.
+* **keycode**: an integer.  allows you to determine which key or mouse button triggered the event and react accordingly.  you can find keycodes [here](http://keycode.info/).
+
+**Usage**:
+```
+/% stow/unstow the ui-bar on double-click %/
+<<event 'dblclick' '#ui-bar'>>
+    <<toggleclass '#ui-bar' 'stowed'>>
+<</event>>
+
+/% set up some hotkeys %/
+<<event 'keyup'>>
+<<which 67>> /% the c key %/
+	<<if not tags().includes('menu')>> /% avoid menu loop %/
+		<<goto 'character-menu'>>
+	<</if>>
+<<which 83>> /% the s key %/
+	<<if not tags().includes('menu')>> /% avoid menu loop %/
+		<<goto 'spells-menu'>>
+	<</if>> 
+<<which 77>> /% the m key %/
+	<<masteraudio mute>>
+<</event>>
+```
+
+### Macro: `<<trigger>>`
+
+**Syntax**:`<<trigger (type) (optional: selector)>>`
+
+Allows you to simulate any event on any element.  This macro is useful for triggering events you may not otherwise have easy access to.
+
+* **type**: a valid jQuery event type
+* **selector**: a valid jQuery/CSS selector.  if omitted, defaults to the document element
+
+**Usage**:
+```
+/% close any dialog box when the player presses esc %/
+<<event 'keydown'>>
+<<which 27>>
+	<<trigger 'click' '#ui-dialog-close'>>
+<</event>>
+```

docs/file-system-macros.md

@@ -18,7 +18,7 @@ The `<<export>>` macro is a way to save a little bit of data on your user's hard
 
  * **data**: Some data, like a variable.
  * **fileName**: The default file name to save the file as.
- * **dataType**: By default, the macro saves the data as a string, and converts to JSON when that isn't possible.  This option gives you a bit more control, and accepts the following arguments:
+ * **dataType**: (optional) By default, the macro saves the data as a string, and converts to JSON when that isn't possible.  This option gives you a bit more control, and accepts the following arguments:
 	 * `text`: the file is saved as text, but may be converted to JSON anyway, if necessary.
 	 * `json`: the file is saved as JSON data.
 	 * `base64`: the file is saved in the compressed base64 format. The object will be converted to JSON first if necessary.
@@ -41,11 +41,11 @@ The `<<import>>` macro can be used to import some data you've previously saved t
 **Arguments**:
 
  * **variableName**: The name of a variable, passed in quotes.  The data pulled from the file will be saved to this variable.
- * **dataType**: The data will be imported as a string, but you can have the string be automatically included if you tell the macro what sort of data you expect:
+ * **dataType**: (optional) The data will be imported as a string, but you can have the string be automatically included if you tell the macro what sort of data you expect:
 	 * `text`: the file will be read and imported as a single string.
 	 * `json`: the file will be read as JSON data and converted back into a JavaScript value or object.
 	 * `base64`: the file will be as base64 format, and converted to a string or object as appropriate.
- * **llinkText**: The text the button should appear with.  Defaults to 'Import'.
+ * **llinkText**: (optional) The text the button should appear with.  Defaults to 'Import'.
 
 **Usage**:
 ```

docs/first-macro.md

@@ -0,0 +1,42 @@
+## The First Macro
+
+[Back to the main readme](https://github.com/ChapelR/custom-macros-for-sugarcube-2/blob/master/readme.md).
+
+Based loosely on Leon's `<<once>>` macro and similar, `<<first>>`, `<<then>>`, and `<<finally>>` create code or text that is shown based on how many times the player has visited a particular passage. While it's nothing that couldn't be handled with variables or `visited()` and an `<<if>>` or `<<switch>>`, I believe this lightweight set of macros feel a bit better to use in some stories. 
+
+**THE CODE:** [Minified](https://github.com/ChapelR/custom-macros-for-sugarcube-2/blob/master/scripts/minified/first-macro.min.js). [Pretty](https://github.com/ChapelR/custom-macros-for-sugarcube-2/blob/master/scripts/first-macro.js).  
+**DEMO:** [Available](http://holylandgame.com/custom-macros.html).  
+**GUIDE:** Not available.
+
+### Macro: `<<first>>`
+
+**Syntax**:`<<first>>...<<then>>...<<finally>>...<</first>>`
+
+A simple, slightly sexier repalcement for `<<if visited()>>` and `<<switch visited()>>`, based loosely on Leon's `<<once>>` macro.  `<<first>>` shows text on the first visit to a passage, and you can use `<<then>>` to show different text on subsequent visits.  Use `<<finally>>` to show text that persists over *all* subsequent visits.  **Note**: Do not nest `<<first>>` macros inside each other; it won't cause an error, but it also likely won't work the way you expect.  If you need nesting, you'll need to use variables.
+
+**Usage**:
+```
+// show something or run code only on first visit to any given passage:
+<<first>>Show only on first visit.<</first>>
+
+// show something only on second and all subsequent visits:
+<<first>><<finally>>Show me on every visit except the first.<</first>> 
+
+// show different text on first three visits, then nothing:
+<<first>>\
+	First visit text.
+<<then>>\
+	Second visit text.
+<<then>>\
+	Third visit text.
+<</first>>
+
+// show different text on first two visits then different text on the third visit and subsequent visits: 
+<<first>>\
+	First visit text.
+<<then>>\
+	Second visit text.
+<<finally>>\
+	Third visit and subsequent visits text.
+<</first>>
+```

docs/fullscreen-macros.md

@@ -0,0 +1,39 @@
+## The Fullscreen Macros
+
+[Back to the main readme](https://github.com/ChapelR/custom-macros-for-sugarcube-2/blob/master/readme.md).
+
+Macros for making your story fullscreen when used in a browser.  Note: these macros may not work in the downloadable release of Twine 2's test and play modes, and may or may not work with various wrappers like NW.js or Electron.  For normal in browser play, they should do fine.
+
+**THE CODE:** [Minified](https://github.com/ChapelR/custom-macros-for-sugarcube-2/blob/master/scripts/minified/fullscreen.min.js). [Pretty](https://github.com/ChapelR/custom-macros-for-sugarcube-2/blob/master/scripts/fullscreen.js).  
+**DEMO:** [Available](http://holylandgame.com/custom-macros.html).  
+**GUIDE:** Not available.
+
+### Macro: `<<fullscreen>>`
+
+**Syntax**:`<<fullscreen>>`
+
+This macro causes the game to go into fullscreen mode, but it must be paired with some sort of interaction to work, like a link or a button.
+
+**Usage**:
+```
+<<link 'Fullscreen Mode'>>
+	<<fullscreen>>
+<</link>>
+
+<<button 'Fullscreen Mode'>>
+	<<fullscreen>>
+<</button>>
+```
+
+### Macro: `<<fullscreenlink>>`
+
+**Syntax**:`<<fullscreenlink linkText>>`
+
+Creates a link with user-defined text that, when clicked, launches fullscreen mode.
+
+ * **linkText**: the text of the link.
+
+**Usage**:
+```
+<<fullscreenlink 'Fullscreen Mode'>>
+```

docs/message-macro.md

@@ -0,0 +1,47 @@
+## The Message Macro
+
+[Back to the main readme](https://github.com/ChapelR/custom-macros-for-sugarcube-2/blob/master/readme.md).
+
+Macros for making your story fullscreen when used in a browser.  Note: these macros may not work in the downloadable release of Twine 2's test and play modes, and may or may not work with various wrappers like NW.js or Electron.  For normal in browser play, they should do fine.
+
+**THE CODE:** [Minified](https://github.com/ChapelR/custom-macros-for-sugarcube-2/blob/master/scripts/minified/fullscreen.min.js). [Pretty](https://github.com/ChapelR/custom-macros-for-sugarcube-2/blob/master/scripts/fullscreen.js).  
+**DEMO:** [Available](http://holylandgame.com/custom-macros.html).  
+**GUIDE:** Not available.
+
+### Macro: `<<message>>`
+
+**Syntax**: `<<message [linkText] [btn] [id]>>`
+
+This macro displays a link or, optionally, a button. The link or button can be clicked to display a message immediately below it in the passage text, and clicked again to collapse the message. 
+
+* **linkText**: (optional) the text of the link.  if omitted, default text is displayed (the default text can be edited above)
+* **btn**: (optional) if `btn` is included in the macro's arguments, a button is generated instead of a link
+* **id**: (optional) if multiple messages are displayed on the same page with the same link text, you need to provide each one with a unique id.
+
+**Usage**:
+```
+<<message>>Text<</message>>
+// creates a link that reads 'Help' (by default) and can be clicked to display the content between the tags and clicked again to collapse the content.
+
+<<message 'click me' btn>>Text<</message>>
+// creates the message with the link text 'click me' and renders it as a button element
+
+<<message 'Click here!' 'uniqueID'>>...<</message>>
+<<message 'Click here!' 'anotherUniqueID'>>...<</message>>
+// creates two messages with the same link text.  they must be given two different, unique IDs to appear in the same passage.
+```
+
+## Othe Usage Notes:
+
+**Styling Options**:
+
+Message content is given the class `.message-text`; you can control the appearance of the message's content using this selector in your CSS. (For example: `.message-text {color: green;}` would render the text of all messages in green).
+
+**Configuration**:
+
+You can alter the `setup.messageMacro.default` configuration option in your story JavaScript to change what the default link text is when you omit the argument.
+
+```javascript
+// <<message>> macros without linkText arguments will display `YAY`:
+setup.messageMacro.default = 'YAY';
+```

docs/notify-macro.md

@@ -0,0 +1,36 @@
+## The Notify Macro
+
+[Back to the main readme](https://github.com/ChapelR/custom-macros-for-sugarcube-2/blob/master/readme.md).
+
+This macro pops a message up that slides out from the right side of the screen, a short notification that's less distracting than a dialog or alert, for things like inventory changes, experience gains, or even achievements.
+
+Note that unlike most of my code, this macro requires you to install the CSS code as well in your story's Stylesheet section.
+
+**THE CODE:** [Minified JS](https://github.com/ChapelR/custom-macros-for-sugarcube-2/blob/master/scripts/minified/notify.min.js)[Minified CSS](https://github.com/ChapelR/custom-macros-for-sugarcube-2/blob/master/scripts/minified/notify.min.css). [Pretty JS](https://github.com/ChapelR/custom-macros-for-sugarcube-2/blob/master/scripts/notify.js)[Pretty CSS](https://github.com/ChapelR/custom-macros-for-sugarcube-2/blob/master/scripts/notify.css).  
+**DEMO:** [Available](http://holylandgame.com/custom-macros.html).  
+**GUIDE:** Not available.
+
+### Macro: `<<notify>>`
+
+**Syntax**:`<<notify [delay] [classList]>>...<</notify>>`
+
+The `<<notify>>` macro displays everything between it's tags in a small message box on the top right of the screen that slides in and slides out after a brief delay.
+
+ * **delay**: (optional) The amount of time the notification should remain visible, in milliseconds (working on getting this to CSS time).  If omitted, the delay defaults to 2 seconds, or `2000`.
+ * **classList**: (optional) An array of strings, list of space seperated stings, or some combination of the two, will be added to the notification as classes for styling.
+
+**Usage**:
+```
+/% a simple, two-second-long notification with no added classes %/
+<<notify>>Achievement unlocked!<</notify>>
+
+/% a one-second-long notification with the 'inventory-update' class %/
+<<notify 1000 'inventory-update'>>Found gold.<</notify>>
+
+/% a lengthy five-second-long notification %/
+<<notify 5000>>$xp experience points earned.<</notify>>
+```
+
+## Other Usage Notes:
+
+Note that giving the player unlimited control over these notifications, or trying to show several at once or right after each other will cause them to trip over themselves as they try to animate, so try to keep them spaced out, and don't assign them to links or buttons you expect the player to press repeatedly.

docs/operations-api.md

@@ -0,0 +1,96 @@
+## The operations API
+
+[Back to the main readme](https://github.com/ChapelR/custom-macros-for-sugarcube-2/blob/master/readme.md).
+
+This is a bunch of functions and methods for performing some useful number- or math-based operations.
+
+**THE CODE:** [Minified](https://github.com/ChapelR/custom-macros-for-sugarcube-2/blob/master/scripts/minified/operations.min.js). [Pretty](https://github.com/ChapelR/custom-macros-for-sugarcube-2/blob/master/scripts/operations.js).  
+**DEMO:** [Available](http://holylandgame.com/custom-macros.html).  
+**GUIDE:** Not available.
+
+### Function: `dice()`
+
+**Syntax**:`dice(diceNotation)` or `dice(numberOfDice, sidesOfDice)`
+
+A function for rolling dice.  The dice to be rolled can be provided as a string of dice notation (i.e. `1d6 + 10`, `4d4-1`, `1d20`), or as sperate arguments (`3d6` becomes `dice(3, 6)`, for example).  This funciton is global, but if it's unavailable, it can be found on the `setup` object under `setup.dice.roll()`.
+
+* **diceNotation**: a string representing dice notation (`'1d6'`, `'6d8'`, `'4d20+8'`, etc).
+* **numberOfDice**: the number of dice to roll.
+* **sidesOfDice**: the sides of each rolled die.
+
+**Usage**:
+```
+/% each <<set>> macro below rolls three six-sided dice and adds to (3d6+2) %/
+
+<<set _roll to dice('3d6+2')>>
+<<set _roll to dice('3d6') + 2>>
+<<set _roll to dice(3, 6) + 2>>
+```
+
+### Method: `Number.prototype.dice()` and `Number.prototype.d()`
+
+**Syntax**:`<numberOfDice>.dice(sidesOfDice)` or `<numberOfDice>.d(sidesOfDice)`
+
+Similar to the `dice()` function, this is another way to roll dice, and exists on the `Number` prototype, meaning it can be called directly on numbers.  `<number>.d()` and `<number>.dice()` do the same thing and can be used interchangeably.
+
+* **numberOfDice**: the number of dice to roll.
+* **sidesOfDice**: the sides of each rolled die.
+
+**Usage**:
+```
+/% each <<set>> macro below rolls three six-sided dice and adds two (3d6+2) %/
+<<set _sides to 6, _num to 3>>
+
+<<set _roll to (3).d(6) + 2>>
+<<set _roll to _num.d(6) + 2>>
+<<set _roll to (3).dice(_sides) + 2>>
+<<set _roll to _num.dice(_sides) + 2>>
+```
+
+### Method: `Number.prototype.fairmath()` and `Number.prototype.fm()`
+
+**Syntax**:`<value>.farimath(change)` or `<value>.fm(change)`
+
+Read more on what fairmath is [here](http://choicescriptdev.wikia.com/wiki/Arithmetic_operators#Fairmath). Basically, a number is changed in a percentile way, and the lower its value, the greater the effect of adding to it, and vice versa, etc.
+
+* **value**: the base value to apply a fairmath change to.
+* **change**: the number to add or subtract from the base value.
+
+**Usage**:
+```
+<<set $stat to 80>>
+<<set $otherStat to 75>>
+
+<<set $stat to $stat.fm(20)>>
+<<set $otherStat to $otherStat.fairmath(-20)>>
+
+<<= $stat>> /% 96 %/
+<<= $otherStat>> /% 60 %/
+```
+
+### Method: `Math.fairmath()` and `Math.fm()`
+
+**Syntax**:`Math.farimath(value, change)` or `Math.fm(value, change)`
+
+The same as `<number>.fairmath()` above, but on the `Math` object, which you may or may not prefer.
+
+* **value**: the base value to apply a fairmath change to.
+* **change**: the number to add or subtract from the base value.
+
+**Usage**:
+```
+<<set $stat to 80>>
+<<set $otherStat to 75>>
+
+<<set $stat to Math.fm($stat, 20)>>
+<<set $otherStat to Math.fairmath($otherStat, -20)>>
+
+<<= $stat>> /% 96 %/
+<<= $otherStat>> /% 60 %/
+```
+
+## Other usage notes:
+
+**Configuration options**:
+
+There are some configuration options you can mess with if you know what you're doing.  Take a look at the unminified script for more.