Custom Macros for SugarCube 2

The Cycles System allows you to introduce rotating states (like time of day, seasons, or days of the week) into your game. You define a cycle with a name, a list of values, and a turn interval. Every time a certain number of turns pass, the cycle moves to the next value in its list, eventually looping back to the start.

Key Behaviors

• Independent Tracking: Each cycle tracks its own turns independently. If you create a cycle mid-game, it starts its turn count from zero at that moment. To ensure cycles stay synchronized, it is recommended to declare all <<newcycle>> macros in the same passage (e.g., StoryInit).
• Resetting/Overwriting: You can overwrite an existing cycle by calling <<newcycle>> with the same name. Note that once a cycle is deleted via <<deletecycle>> or overwritten, it cannot be reclaimed.
• Suspension: Instead of deleting a cycle you might need later, use <<suspendcycle>> to freeze it in its current state.
• Data Storage: Cycles are stored in a story variable (defaulting to $cycles), making them compatible with SugarCube's built-in save/load system.

// Example of creating a synchronized time cycle
<<newcycle 'time' 'morning' 'noon' 'night' 5>>

Meters trigger two specific events during their animation lifecycle. These events are triggered on the meter's element (meter.$element) and bubble up to the document. The event object contains a meter property which is the Meter instance that triggered the event.

• :meter-animation-start: Triggered when an animation begins.
• :meter-animation-complete: Triggered when an animation finishes.

Usage in JavaScript:

Meter.get('healthBar').on(':meter-animation-start', function () {
    console.log('Animation started!');
});

Usage in TwineScript:

<<newmeter 'healthBar'>><</newmeter>>
<<script>>
   Meter.get('healthBar').on(':meter-animation-complete', function () {
        console.log('Animation finished!');
    });
<</script>>

var meter = Meter.add('healthBar');

meter.on(':meter-animation-start', function () {
    alert('Your health has changed.');
});

The Consumables System is a two-phase system for managing items that can be used and depleted (like potions or spells).

1. Definition Phase: You define a consumable using the <<newconsumable>> macro. This should typically be done in your StoryInit special passage. A definition includes a display name, a unique ID, the code to run when used, and an optional description.
2. Manipulation Phase: Once defined, you can add items to the player's inventory, remove them, use them, or list them using various macros and functions.

Key Constraints:

• Consumables are not widgets. While they fire code chunks, they are less functional than widgets and should not be used as a direct replacement for them.
• The consumable inventory is a separate entity from the 'Simple Inventory' system; they cannot manage each other.

/* Example of the two-phase workflow */

/* 1. Define in StoryInit */
<<newconsumable 'health potion' 'hpPot'>>
	<<set $hp += 20>>
<<description 'hp-desc'>>
<</newconsumable>>

/* 2. Manipulate in game passages */
<<addconsumable 'hpPot' 1>>
<<useconsumable 'hpPot'>>

The Cycles System is a time-keeping mechanism based on passage transitions (turns). Each transition typically adds a value to a cycle's 'stack'. When the stack reaches a defined period, the cycle advances to the next phase.

Key Concepts:

• Turn: A single passage transition.
• Stack: A counter that tracks progress toward the next phase.
• Period: The threshold value the stack must reach to trigger a phase change.
• Increment: The amount added to the stack per turn. While usually 1, increasing the increment allows you to effectively shorten the period without changing the fixed period value.
• Phase: A named state (e.g., 'morning', 'night') that the cycle cycles through.

Note: This version is not compatible with code written for version 1.x of the system.

/* Concept Example: A cycle that changes phase every 4 turns */
<<newcycle 'time' 4>>
    <<phase 'morning' 'midday' 'evening' 'night'>>
<</newcycle>>