v2.5.5

- cycles check() methods update
- clean up docs

docs/README.md

@@ -1,4 +1,4 @@
-## Chapel's Custom Macro Collection (v2.5.4)
+## Chapel's Custom Macro Collection (v2.5.5)
 
 - [Try the demo!](https://macros.twinelab.net/demo)
 - [Downloads](./download ':ignore')
@@ -8,7 +8,7 @@
 ### Documentation
 - **Gameplay Systems and Mechanics**
   - [The Simple Inventory System](./simple-inventory.md)
-  - [The Cycles System](./cycles-system.md) *updated*
+  - [The Cycles System](./cycles-system.md)
   - [The Playtime System](./playtime-system.md)
 - **Interface and Style**
   - [The Dialog API Macro Set](./dialog-api-macro-set.md)
@@ -45,7 +45,7 @@ If you opt to get the files from GitHub, It is highly recommended that you insta
 
 - For **Twine 2** users: copy and paste the JavaScript code into your [story JavaScript area](https://twinery.org/wiki/twine2:adding_custom_javascript_and_css).  Some macros may also require CSS code, which goes in your story stylesheet.
 
-- For **Twine 1**, you'll need to copy and paste the JavaSCript portions into a script-tagged passage, and the CSS portions (if any) into a stylesheet-tagged passage. You can create new passages and add the tags yourself, or right-click on a blank spot in the editor and select new script here and new stylesheet here to generate each passage.
+- For **Twine 1**, you'll need to copy and paste the JavaScript portions into a script-tagged passage, and the CSS portions (if any) into a stylesheet-tagged passage. You can create new passages and add the tags yourself, or right-click on a blank spot in the editor and select new script here and new stylesheet here to generate each passage.
 
 - For **Twee2**, refer to [its documentation](https://dan-q.github.io/twee2/documentation.html#twee2-syntax-special-passages) for how to create the tagged passages you need.
 

docs/changelog.md

@@ -1,9 +1,10 @@
 ## Changelog
 
-[Back to the main readme](./README.md).
+[Back to the main page](./README.md).
 
-> [!NOTE]
-> I'm going to start keeping a changelog for these macros because keeping track of them is becoming a nightmare. The overall version numbers are not really helpful for tracking what's happening on a macro-by-macro basis, but I'm trying to stick to major version bumps meaning breaking changes in any macro, or complete refactors of the whole collection, like what v2.0.0 was. Minor version updates indicate new macros have been added. Patch version updates means individual macro updates and bug fixes, or documentation, website, or demo updates.
+### June 28, 2020 (v2.5.5)
+
+- **[Update]** Updated `Cycle.check()` and `cycle#check()` to accept multiple phases to check.
 
 ### June 27, 2020 (v2.5.4)
 

docs/cycles-system.md

@@ -261,14 +261,14 @@ var cycle = Cycle.get('blah');
 
 **Returns**: boolean.
 
-**Syntax**: `Cycle.check(name, phase)`
+**Syntax**: `Cycle.check(name, phase [, phase...])`
 
-Returns a whether the indicated `Cycle` instance is at the indicated phase
+Returns a whether the indicated `Cycle` instance is any of the indicated phases. You may pass any number of phases as an array, or as separate arguments, or as any combination of arrays and separate arguments. If the cycle is currently at any of the phases, this method will return `true`.
 
 **Arguments**:
 
 - `name`: The name of a previously defined cycle, by the [`<<newcycle>>` macro](#macro-ltltnewcyclegtgt) or the [`Cycle` API](#javascript-api).
-- `phase`: The string name of one of the phases in this cycle.
+- `phase`: The string name of one of the phases in this cycle. You may pass any number of phases as a series of arguments or as an array, or as any combination of the two.
 
 **Usage**:
 
@@ -345,13 +345,13 @@ Cycle.get('blah').current();
 
 **Returns**: boolean.
 
-**Syntax**: `<cycle>.check(phase)`
+**Syntax**: `<cycle>.check(phase [, phase...])`
 
-Returns whether the cycle is at the indicated phase.
+Returns whether the cycle is at the indicated phase. You may pass any number of phases as an array, or as separate arguments, or as any combination of arrays and separate arguments. If the cycle is currently at any of the phases, this method will return `true`.
 
 **Arguments**:
 
-- `phase`: The string name of one of the phases in this cycle.
+- `phase`: The string name of one of the phases in this cycle. You may pass any number of phases as a series of arguments or as an array, or as any combination of the two.
 
 **Usage**:
 

docs/demo/index.html

@@ -174,7 +174,7 @@
 // end css-macro.min.js
 /* twine-user-script #6: "cycles.min.js" */
 // cycles.min.js, for SugarCube 2, by Chapel
-;!function(){"use strict";var e="%%cycles",t=!0,r="cycles.pause",i="cycles.pause.menu",n="cycles.postdisplay";function s(){return State.variables[e]}function a(e,t){if(!(this instanceof a))return new a(e,t);if(!e||"object"!=typeof e)throw new Error("Cycle() -> invalid definition object");if(!e.name||"string"!=typeof e.name||!e.name.trim())throw new Error("Cycle() -> invalid name");if(this.name=e.name,!e.phases||!Array.isArray(e.phases)||e.phases.length<2)throw new Error("Cycle() -> phases should be an array of at least two strings");if(!e.phases.every((function(e){return e&&"string"==typeof e&&e.trim()})))throw new Error("Cycle() -> each phase should be a valid, non-empty string");this.phases=clone(e.phases),e.period=Number(e.period),(Number.isNaN(e.period)||e.period<1)&&(e.period=1),Number.isInteger(e.period)||(e.period=Math.trunc(e.period)),this.period=e.period,e.increment=Number(e.increment),(Number.isNaN(e.increment)||e.increment<1)&&(e.increment=1),Number.isInteger(e.increment)||(e.increment=Math.trunc(e.increment)),this.increment=e.increment,this.active=void 0===e.active||!!e.active,t=Number(t),(Number.isNaN(t)||t<0)&&(t=0),Number.isInteger(t)||(t=Math.trunc(t)),this.stack=t}State.variables[e]={},Object.assign(a,{is:function(e){return e instanceof a},add:function(e,t){if(!t||"object"!=typeof t)throw new Error("Cycle.add() -> invalid definition object");if(e&&"string"==typeof e&&e.trim())t.name=e;else if(!t.name||"string"!=typeof t.name||!t.name.trim())throw new Error("Cycle.add() -> invalid name");var r=new a(t,0);return s()[t.name]=r,r},has:function(e){var t=s();return t.hasOwnProperty(e)&&a.is(t[e])},get:function(e){return a.has(e)?s()[e]:null},del:function(e){return!!a.has(e)&&(delete s()[e],!0)},check:function(e,t){if(a.has(e))return a.get(e).check(t)},clear:function(e){s()},_emit:function(e,t){$(document).trigger({type:":cycle-"+t,cycle:e})},_retrieveCycles:s}),Object.assign(a.prototype,{constructor:a,revive:function(){var e={};return Object.keys(this).forEach((function(t){e[t]=clone(this[t])}),this),e},clone:function(){return new a(this.revive(),this.stack)},toJSON:function(){return JSON.reviveWrapper("new setup.Cycle("+JSON.stringify(this.revive())+", "+this.stack+")")},current:function(){return this.phases[Math.trunc(this.stack/this.period)%this.phases.length]},length:function(){return this.period*this.phases.length},turns:function(){return this.period/this.increment},turnsTotal:function(){return this.length()/this.increment},update:function(e){e=Number(e),Number.isNaN(e)&&(e=this.increment);var t=this.current();return this.stack+=e,this.stack<0&&(this.stack=0),Number.isInteger(this.stack)||(this.stack=Math.trunc(this.stack)),t!==this.current()&&a._emit("change"),this},reset:function(){return this.stack=0,a._emit(this,"reset"),this.update(0)},suspend:function(){var e=this.active;return this.active=!1,e!==this.active&&a._emit(this,"suspend"),this},resume:function(){var e=this.active;return this.active=!0,e!==this.active&&a._emit(this,"resume"),this},toggle:function(){return this.active?this.suspend():this.resume(),this},isSuspended:function(){return!this.active},editIncrement:function(e){return e=Number(e),(!Number.isNaN(e)||e>0)&&(Number.isInteger(e)||(e=Math.trunc(e)),this.increment=e),this.increment},check:function(e){return this.current()===e}}),postdisplay[n]=function(){var e;tags().includes(r)||e?e=!1:tags().includes(i)?e=!0:Object.keys(s()).forEach((function(e){var t=a.get(e);t.active&&t.update()}))},setup.Cycle=a,t&&(window.Cycle=window.Cycle||a),Macro.add("newcycle",{tags:["phase"],handler:function(){if(this.args.length<1)return this.error("A cycle must at least be given a name.");if(this.payload.length<2)return this.error("A cycle must be given at least two phases.");var e=this.payload.slice(1).map((function(e){return function(e){if(e.args.length<1)return null;var t=e.args.flatten();return t.every((function(e){return"string"==typeof e}))?t:null}(e)})).flatten();if(e.includes(null))return this.error("Each `<<phase>>` tag must be given a valid name.");try{a.add(this.args[0],{phases:e,period:this.args[1],increment:this.args[2],active:this.args[3]&&"string"==typeof this.args[3]&&"suspend"!==this.args[3].trim()})}catch(e){var t=e.message&&e.message.split("->")[1];return t=!!t&&t.trim(),this.error(t||e.message)}}}),Macro.add("editcycle",{handler:function(){if(this.args.length<1||"string"!=typeof this.args[0]||!this.args[0].trim())return this.error("You must name the cycle you wish to act on.");if(this.args.length<2)return this.error("You must provide an action to perform.");var e=a.get(this.args[0]);if(null===e)return this.error('Cannot find a cycle named "'+this.args[0]+'".');if(this.args.includes("suspend")?e.suspend():this.args.includes("toggle")?e.toggle():this.args.includes("resume")&&e.resume(),this.args.includes("increment")){var t=this.args[this.args.indexOf("increment")+1];"number"==typeof t&&e.editIncrement(t)}if(this.args.includesAny("reset","clear")&&e.reset(),this.args.includes("change")){var r=this.args[this.args.indexOf("change")+1];r=Number(r),!Number.isNaN(r)&&Number.isInteger(r)&&e.update(r)}}}),Macro.add("showcycle",{handler:function(){if(this.args.length<1||"string"!=typeof this.args[0]||!this.args[0].trim())return this.error("You must name the cycle you wish to act on.");var e=a.get(this.args[0]);if(null===e)return this.error('Cannot find a cycle named "'+this.args[0]+'".');var t=e.current();this.args.includes("uppercase")?t=t.toUpperCase():this.args.includes("lowercase")?t=t.toLowerCase():this.args.includes("upperfirst")&&(t=t.toUpperFirst()),$(document.createElement("span")).addClass("macro-"+this.name).append(t).appendTo(this.output)}})}();
+;!function(){"use strict";var e="%%cycles",t=!0,r="cycles.pause",i="cycles.pause.menu",n="cycles.postdisplay";function s(){return State.variables[e]}function a(e,t){if(!(this instanceof a))return new a(e,t);if(!e||"object"!=typeof e)throw new Error("Cycle() -> invalid definition object");if(!e.name||"string"!=typeof e.name||!e.name.trim())throw new Error("Cycle() -> invalid name");if(this.name=e.name,!e.phases||!Array.isArray(e.phases)||e.phases.length<2)throw new Error("Cycle() -> phases should be an array of at least two strings");if(!e.phases.every((function(e){return e&&"string"==typeof e&&e.trim()})))throw new Error("Cycle() -> each phase should be a valid, non-empty string");this.phases=clone(e.phases),e.period=Number(e.period),(Number.isNaN(e.period)||e.period<1)&&(e.period=1),Number.isInteger(e.period)||(e.period=Math.trunc(e.period)),this.period=e.period,e.increment=Number(e.increment),(Number.isNaN(e.increment)||e.increment<1)&&(e.increment=1),Number.isInteger(e.increment)||(e.increment=Math.trunc(e.increment)),this.increment=e.increment,this.active=void 0===e.active||!!e.active,t=Number(t),(Number.isNaN(t)||t<0)&&(t=0),Number.isInteger(t)||(t=Math.trunc(t)),this.stack=t}State.variables[e]={},Object.assign(a,{is:function(e){return e instanceof a},add:function(e,t){if(!t||"object"!=typeof t)throw new Error("Cycle.add() -> invalid definition object");if(e&&"string"==typeof e&&e.trim())t.name=e;else if(!t.name||"string"!=typeof t.name||!t.name.trim())throw new Error("Cycle.add() -> invalid name");var r=new a(t,0);return s()[t.name]=r,r},has:function(e){var t=s();return t.hasOwnProperty(e)&&a.is(t[e])},get:function(e){return a.has(e)?s()[e]:null},del:function(e){return!!a.has(e)&&(delete s()[e],!0)},check:function(e){if(a.has(e)){var t=[].slice.call(arguments).flatten().slice(1);return a.get(e).check(t)}},clear:function(e){s()},_emit:function(e,t){$(document).trigger({type:":cycle-"+t,cycle:e})},_retrieveCycles:s}),Object.assign(a.prototype,{constructor:a,revive:function(){var e={};return Object.keys(this).forEach((function(t){e[t]=clone(this[t])}),this),e},clone:function(){return new a(this.revive(),this.stack)},toJSON:function(){return JSON.reviveWrapper("new setup.Cycle("+JSON.stringify(this.revive())+", "+this.stack+")")},current:function(){return this.phases[Math.trunc(this.stack/this.period)%this.phases.length]},length:function(){return this.period*this.phases.length},turns:function(){return this.period/this.increment},turnsTotal:function(){return this.length()/this.increment},update:function(e){e=Number(e),Number.isNaN(e)&&(e=this.increment);var t=this.current();return this.stack+=e,this.stack<0&&(this.stack=0),Number.isInteger(this.stack)||(this.stack=Math.trunc(this.stack)),t!==this.current()&&a._emit("change"),this},reset:function(){return this.stack=0,a._emit(this,"reset"),this.update(0)},suspend:function(){var e=this.active;return this.active=!1,e!==this.active&&a._emit(this,"suspend"),this},resume:function(){var e=this.active;return this.active=!0,e!==this.active&&a._emit(this,"resume"),this},toggle:function(){return this.active?this.suspend():this.resume(),this},isSuspended:function(){return!this.active},editIncrement:function(e){return e=Number(e),(!Number.isNaN(e)||e>0)&&(Number.isInteger(e)||(e=Math.trunc(e)),this.increment=e),this.increment},check:function(){var e=[].slice.call(arguments).flatten();return e.includes(this.current())}}),postdisplay[n]=function(){var e;tags().includes(r)||e?e=!1:tags().includes(i)?e=!0:Object.keys(s()).forEach((function(e){var t=a.get(e);t.active&&t.update()}))},setup.Cycle=a,t&&(window.Cycle=window.Cycle||a),Macro.add("newcycle",{tags:["phase"],handler:function(){if(this.args.length<1)return this.error("A cycle must at least be given a name.");if(this.payload.length<2)return this.error("A cycle must be given at least two phases.");var e=this.payload.slice(1).map((function(e){return function(e){if(e.args.length<1)return null;var t=e.args.flatten();return t.every((function(e){return"string"==typeof e}))?t:null}(e)})).flatten();if(e.includes(null))return this.error("Each `<<phase>>` tag must be given a valid name.");try{a.add(this.args[0],{phases:e,period:this.args[1],increment:this.args[2],active:this.args[3]&&"string"==typeof this.args[3]&&"suspend"!==this.args[3].trim()})}catch(e){var t=e.message&&e.message.split("->")[1];return t=!!t&&t.trim(),this.error(t||e.message)}}}),Macro.add("editcycle",{handler:function(){if(this.args.length<1||"string"!=typeof this.args[0]||!this.args[0].trim())return this.error("You must name the cycle you wish to act on.");if(this.args.length<2)return this.error("You must provide an action to perform.");var e=a.get(this.args[0]);if(null===e)return this.error('Cannot find a cycle named "'+this.args[0]+'".');if(this.args.includes("suspend")?e.suspend():this.args.includes("toggle")?e.toggle():this.args.includes("resume")&&e.resume(),this.args.includes("increment")){var t=this.args[this.args.indexOf("increment")+1];"number"==typeof t&&e.editIncrement(t)}if(this.args.includesAny("reset","clear")&&e.reset(),this.args.includes("change")){var r=this.args[this.args.indexOf("change")+1];r=Number(r),!Number.isNaN(r)&&Number.isInteger(r)&&e.update(r)}}}),Macro.add("showcycle",{handler:function(){if(this.args.length<1||"string"!=typeof this.args[0]||!this.args[0].trim())return this.error("You must name the cycle you wish to act on.");var e=a.get(this.args[0]);if(null===e)return this.error('Cannot find a cycle named "'+this.args[0]+'".');var t=e.current();this.args.includes("uppercase")?t=t.toUpperCase():this.args.includes("lowercase")?t=t.toLowerCase():this.args.includes("upperfirst")&&(t=t.toUpperFirst()),$(document.createElement("span")).addClass("macro-"+this.name).append(t).appendTo(this.output)}})}();
 // end cycles.min.js
 /* twine-user-script #7: "dialog-api-macro-set.min.js" */
 // dialog-api-macro-set.min.js, for SugarCube 2, by Chapel

package.json

@@ -1,6 +1,6 @@
 {
   "name": "custom-macros-for-sugarcube-2",
-  "version": "2.5.4",
+  "version": "2.5.5",
   "description": "Collection of custom macros and systems for Twine/SugarCube2.",
   "main": "build.js",
   "directories": {

scripts/cycles.js

@@ -1,7 +1,7 @@
 (function () {
     'use strict';
     // cycles.js, by chapel; for SugarCube 2
-    // version 2.0.0
+    // version 2.1.1
 
     // OPTIONS
 
@@ -139,9 +139,10 @@
             }
             return false;
         },
-        check : function (name, phase) {
+        check : function (name) {
             if (Cycle.has(name)) {
-                return Cycle.get(name).check(phase);
+                var phases = [].slice.call(arguments).flatten().slice(1);
+                return Cycle.get(name).check(phases);
             }
         },
         clear : function (name) {
@@ -254,8 +255,9 @@
             }
             return this.increment;
         },
-        check : function (phase) {
-            return this.current() === phase;
+        check : function () {
+            var phases = [].slice.call(arguments).flatten();
+            return phases.includes(this.current());
         }
     });