chapel.twee-config.yaml

sugarcube-2:

  macros:
  
    # start simple inventory
    newinventory:
      name: newinventory
      description: |-
        *Syntax:* `<<newinventory variableName [itemList]>>`

        This macro creates a new inventory. Creating a new inventory is much like initializing a variable, and the best place to use this macro is in your StoryInit special passage. You must provide the macro with a valid TwineScript variable, passed in quotes (similar to how you might pass it to a <<textbox>> macro). The new inventory will be stored in the provided variable. You can optionally pass the inventory a list of items and the inventory will be initialized with these items inside it.

        *Arguments:*

          * `variableName`: The name of a $variable, which must be quoted, in which to store the newly created inventory.
          * `itemList`: (optional) A list of items to place in the inventory. This list should be one or more arrays of quoted strings, a space-separated list of quoted strings, or any combination of the two. If you use array literals directly in the macro's arguments, you need to wrap them in backticks (`). See "Passing an expression as an argument" [in the SugarCube docs](http://www.motoslave.net/sugarcube/2/docs/#macros-arguments).

        *Usage:*
        ```
        /% create a new, empty inventory in the $inventory variable %/
        <<newinventory '$inventory'>>

        /% create an inventory in the $playerInventory variable and place two items in it %/
        <<newinventory '$playerInventory' 'a pair of shoes' 'the shirt on your back'>>

        /% create an inventory for the kitchen room and call it $kitchenInventory and place some items in it %/
        <<newinventory '$kitchenInventory' `['a steak knife', 'a blender']` 'a calender'>>

        /% create a suit case called $suitCase always contains a key, but also includes some random items %/
        <<set _items to ['keys', 'a suit', 'a laptop', 'a cellphone', 'a wallet', 'sixteen cents', 'a hairpin', 'toothpaste', 'glue'].pluckMany(3)>>
        <<newinventory '$suitCase' _items 'car key'>>
        ```
      parameters:
        - string |+ ...text
    pickup:
      name: pickup
      description: |-
        *Syntax:* `<<pickup variableName [unique] itemList>>`

        The `<<pickup>>` macro adds items to inventory indicated by the $variable. These items are added to the end of the inventory. If the keyword `unique` is included before the item list, items that are already in the inventory will not be added to it. *Caution:* if the `unique` keyword is placed after the first item in the item list, an item called `unique` will be added to the inventory.

        *Arguments:*

          * `variableName`: The name of a $variable, which must be quoted, and which is storing an inventory created by `<<newinventory>>` or the `Inventory()` constructor.
          * `unique`: (optional) The keyword `unique`. If passed before the item list, will enforce uniqueness--that is, items already in the inventory will not be picked up.
          * `itemList`: A list of items to place in the inventory. This list should be one or more arrays of quoted strings, a space-separated list of quoted strings, or any combination of the two. If you use array literals directly in the macro's arguments, you need to wrap them in backticks (`). See "Passing an expression as an argument" [in the SugarCube docs](http://www.motoslave.net/sugarcube/2/docs/#macros-arguments).

        *Usage:*
        ```
        /% add an item to the inventory %/
        <<pickup '$inventory' 'baseball card'>>

        /% you may wish to check if the player already has the item: %/
        @@#link;
        <<link 'Pick up the gun.'>>
          <<if $playerInventory.has('a gun')>>
            <<replace '#links'>>You already have a gun, you don't need another...<</replace>>
          <<else>>
            <<pickup '$playerInventory' 'a gun'>>
            <<replace '#link'>>You take the gun and hide it in your coat.<</replace>>
          <</if>>
        <</link>>
        @@

        /% you can also add several items at once %/
        You received your inheritance!
        <<set _randomItem to either('a bust of George Washinton', 'a pearl necklace', 'a statue of a cherub')>>
        <<pickup '$maryInventory _randomItem 'a large sum of money' 'a sealed letter'>>

        /% unique items: %/
        :: StoryInit
        <<newinventory '$inventory' 'sword'>>

        :: A Later Passage
        <<pickup '$inventory' unique 'sword' 'shield'>>
        /% only shield is added %/

        :: Some Other Passage
        /% however, be warned: %/
        <<pickup '$inventory' 'armor' unique 'sword'>>
        /%
          an item named 'unique' is added to the inventory, 
          and the other items are also added, regardless of whether 
          they were already in the inventory
        %/
        ```
      parameters:
        - string &+ ...text
        - string &+ 'unique' &+ ...text
    drop:
      name: drop
      description: |-
        *Syntax:* `<<drop variableName itemList>>`

        The `<<drop>>` macro removes items from the inventory indicated by the $variable. If one or more of the provided items can't be found in the inventory, nothing happens and no error is thrown, so some caution may be required in debugging certain situations.

        *Arguments:*

          * `variableName`: The name of a $variable, which must be quoted, and which is storing an inventory created by `<<newinventory>>` or the `Inventory()` constructor.
          * `itemList`: A list of items to remove from the inventory. This list should be one or more arrays of quoted strings, a space-separated list of quoted strings, or any combination of the two. If you use array literals directly in the macro's arguments, you need to wrap them in backticks (`). See "Passing an expression as an argument" [in the SugarCube docs](http://www.motoslave.net/sugarcube/2/docs/#macros-arguments).

        *Usage:*
        ```
        /% drop an item %/
        <<drop '$inventory' 'baseball card'>>

        /% have a random item stolen %/
        <<set _stolen to $playerInventory.toArray().random()>>
        <<drop '$playerInventory' _stolen>>

        /% drop all weapons %/
        :: StoryInit
        <<newinventory '$player' 'a sword'>>
        <<set $weaponsList to ['a sword', 'a gun', 'shotgun', 'the magic blade of null']>>

        :: Prison
        The guards frisk you and take your weapons.
        <<drop '$player' $weaponList>>
        /% drops any item from _weaponList, if present %/
        ```
      parameters:
        - string &+ ...text
    dropall:
      name: dropall
      description: |-
        *Syntax:* `<<dropall variableName>>`

        The `<<dropall>>` macro removes all items from the inventory indicated by the $variable. The `<<clear>>` macro is an alternative that does the same thing.

        Arguments:

          * `variableName`: The name of a $variable, which must be quoted, and which is storing an inventory created by `<<newinventory>>` or the `Inventory()` constructor.

        *Usage:*
        ```
        /% clears the inventory %/
        <<dropall '$inventory'>>
        ```
      parameters:
        - string
    clear: 
      name: clear
      description: |-
        *Syntax:* `<<clear variableName>>`

        The `<<clear>>` macro removes all items from the inventory indicated by the $variable. The `<<dropall>>` macro is an alternative that does the same thing.

        Arguments:

          * `variableName`: The name of a $variable, which must be quoted, and which is storing an inventory created by `<<newinventory>>` or the `Inventory()` constructor.

        *Usage:*
        ```
        /% clears the inventory %/
        <<clear '$inventory'>>
        ```
      parameters:
        - string
    transfer:
      name: transfer
      description: |-
        *Syntax:* `<<transfer variableName variableName itemList>>`

        The `<<transfer>>` macro moves items from one inventory to another. The first inventory argument is the giver, and the second is the receiver. It's essentially the same as pairing a `<<pickup>>` and `<<drop>>`, but has a few benefits over doing it that way. For one, if you were to <<drop>> an item from one inventory and have another `<<pickup>>` the same item, you run the risk of having the reveiving inventory getting an item that the first inventory never had, since `<<drop>>` does nothing if the item doesn't exist. Using `<<transfer>>`, if an item isn't present in the first inventory, the second inventory will not receive said item. Like `<<drop>>` no error will be raised in this case.

        *Arguments:*

          * `variableName`: The name of a $variable, which must be quoted, and which is storing an inventory created by `<<newinventory>>` or the `Inventory()` constructor.
          * `itemList`: A list of items to transfer between the inventories. This list should be one or more arrays of quoted strings, a space-separated list of quoted strings, or any combination of the two. If you use array literals directly in the macro's arguments, you need to wrap them in backticks (`). See "Passing an expression as an argument" [in the SugarCube docs](http://www.motoslave.net/sugarcube/2/docs/#macros-arguments).

        *Usage:*
        ```
        /% containers %/
        <<link 'Leave the kitchen knife here?'>>
          <<transfer '$playerInventory' '$kitchenInventory' 'kitchen knife'>>
        <</link>>

        /% transfer weapons, so the player can get them back %/
        :: StoryInit
        <<newinventory '$player' 'a sword'>>
        <<newinventory '$holding'>>
        <<set $weaponsList to ['a sword', 'a gun', 'shotgun', 'the magic blade of null']>>

        :: Prison
        The guards frisk you and take your weapons.
        <<trandfer '$player' '$holding' $weaponList>>

        :: Release
        You've been released from prison, and your weapons are returned to you.
        <<transfer '$holding' '$player' $weaponList>>
        ```
      parameters:
        - string string ...text
    sort:
      name: sort
      description: |-
        *Syntax:* `<<sort variableName>>`

        The `<<sort>>` macro sorts the indicated inventory in alphanumeric order.

          > [!WARNING] There's no easy way to restore the default chronological ordering.

        *Arguments:*

          * `variableName`: The name of a $variable, which must be quoted, and which is storing an inventory created by `<<newinventory>>` or the `Inventory()` constructor.

        *Usage:*
        ```
        <<sort '$inventory'>>
        ```
      parameters:
        - string
    inventory:
      name: inventory
      description: |-
        *Syntax:* `<<inventory variableName [separator]>>`

        The `<<inventory>>` macro displays a list of the items in the indicated inventory. This list can be separated by a provided string. If no serparator argument is provided, the default separator is used.

        *Arguments:*

          * `variableName`: The name of a $variable, which must be quoted, and which is storing an inventory created by `<<newinventory>>` or the `Inventory()` constructor.
          * `separator`: (optional) The string used to separate the list of items. If omitted, the [default string](https://github.com/HaleyScribe/custom-macros-for-sugarcube-2/blob/master/docs/simple-inventory.md#option-defaultstrings) is used.

        *Usage:*

        Assume the inventory `$playerInv` contains: `'wallet'`, `'keys'`, `'phone'`, `'pocket knife'`, and `'candy bar'`.

        Example:
        ```
        <<inventory '$playerInv' '\n'>> /% or just <<inventory '$playerInv'>> if the default strings aren't changed %/
        ```
        Result:
        ```
        wallet
        keys
        phone
        pocket knife
        candy bar
        ```
        Example:
        ```
        <<inventory '$playerInv' ', '>>
        ```
        Result:
        ```
        wallet, keys, phone, pocket knife, candy bar
        ```
        Example:
        ```
        <<sort>>
        <<inventory '$playerInv' ' - '>>
        ```
        Result:
        ```
        candy bar - keys - phone - pocket knife - wallet
        ```
      parameters:
        - string |+ string
    linkedinventory:
      name: linkedinventory
      description: |-
        *Syntax:* `<<linkedinventory actionName variableName [variableName]>>`

        The `<<linkedinventory>>` macro creates a list of items from the indicated inventory, and pairs each item with a link. If only one inventory variable is provided, the links, when clicked, will cause the items to be dropped from their current inventory as though the `<<drop>>` macro had been used. If a second inventory variable is included, items will instead be move from the first inventory to the second, as though the `<<transfer>>` macro had been called. The *actionName* argument should be used to contextualize this action for the player.

        *Arguments:*

          * `actionName`: The name the link should be given for each entry. Use an empty string to shortcut to the [default action](https://github.com/HaleyScribe/custom-macros-for-sugarcube-2/blob/master/docs/simple-inventory.md#option-defaultstrings).
          * `variableName`: The name of a $variable, which must be quoted, and which is storing an inventory created by `<<newinventory>>` or the `Inventory()` constructor.

        *Usage:*
        ```
        /% containers %/
        You open the box.  Want to take anything with you?
        <<linkedinventory 'Pick Up' '$boxInventory' '$playerInventory'>>

        /% let the player drop items %/
        <<linkedinventory 'Drop' '$inventory'>>

        /% let the player place items %/
        You open the closet.  Lots of space in here.
        <<linkedinventory 'Store' '$inventory' '$storage'>>
        ```
      parameters:
        - string &+ string |+ string
    # end simple inventory
    
    # start cycles system
    newcycle:
      container: true
      children:
        - phase
    phase:
      parents:  
        - newcycle
    editcycle: {}
    showcycle: {}
    # end cycles system
    
    # start playtime system
    playtime: {}
    # end playtime system
    
    # start dialog api macros
    dialog:
      name: dialog
      container: true
      children:
        - onopen
        - onclose
        - dialogclose
      description: |-
        *Syntax:* `<<dialog [title] [classList]>> <</dialog>>`
        
        The `<<dialog>>` macro creates a new dialog box, with an optional title and an optional list of classes for styling. The content between the macro tags is parsed and appended to the dialog box's body. You will generally want to pair this with some type of interaction, like a link or button. You can use the child tags `<<onopen>>` and `<<onclose>>` to run TwineScript code when the dialog is opened and closed (see below).
        
        *Arguments:*
            *title:* (optional) A title to appear at the top of the dialog box. If you want to omit a title but include classes, this argument can be an empty string (`''`).
            *classList:* (optional) A list of CSS classes to add to the dialog, for styling. The classes should be a space-separated list of quoted class names (i.e. `'class-a' 'class-b' 'class-c'`), a quoted list of space-separated class names (i.e. `'class-a class-b class-c'`), or one or more string arrays (i.e. `['class-a', 'class-b', 'class-c']`), or any combination of thereof.
            
        *Usage:*
        ```
        /% creates a link that opens a dialog box called 'Character Sheet' with the classes .char-sheet and .stats %/
        <<link 'View Character Sheet'>>
          <<dialog 'Character Sheet' 'char-sheet stats'>>\
            |Strength|$str|
            |Dexterity|$dex|
            |Wisdom|$wis|\
          <</dialog>>
        <</link>>
        
        /% create an about button for your credits %/
        <<button 'About'>>
          <<dialog 'Credits'>>\
            This game was made by John P. Nottingham in Twine!\
          <</dialog>>
        <</button>>
        
        /% a dialog with no title or classes %/
        <<link 'Hello!'>>
          <<dialog>>Greetings!<</dialog>>
        <</link>>
        ```
      parameters:
        - (|+ string |+ ...string)
    onopen:
      name: onopen
      container: true
      parents:
        - dialog
      description: |-
        You can use this child tag to run code when the dialog is opened.

        *Usage:*
        ```
        <<link 'View Character Sheet'>>
          <<dialog 'Character Sheet' 'char-sheet stats'>>\
            |Strength|$str|
            |Dexterity|$dex|
            |Wisdom|$wis|\
          <<onopen>>
            <<audio 'click' volume 1 play>>
          <</dialog>>
        <</link>>
        ```
    onclose:
      name: onclose
      container: true
      parents:
        - dialog
      description: |-
        You can use this child tag to run code when the dialog is closed.

        *Usage:*
        ```
        <<link 'View Character Sheet'>>
          <<dialog 'Character Sheet' 'char-sheet stats'>>\
            |Strength|$str|
            |Dexterity|$dex|
            |Wisdom|$wis|\
          <<onopen>>
            <<audio 'click' volume 1 play>>
          <<onclose>>
            <<audio 'close' volume 1 play>>
          <</dialog>>
        <</link>>
        ```
    popup:
      name: popup
      description: |-
        *Syntax:* `<<popup passageName [title] [classList]>>`

        The `<<popup>>` macro provides a similar result to what you might get by pairing a `<<dialog>>` macro and an `<<include>>` macro.
        The macro is generally the same as `<<dialog>>`, but the first argument must be the name of a passage, and instead of rendering content from between tags, that passage's content will be rendered into the dialog box.
        This macro does not support the `<<onopen>>` and `<<onclose>>` feature; if you need it, use the `<<dialog>>` macro with `<<include>>`.

        *Arguments:*

            *passageName:* The name of one of your passages. The indicated passage's content will be rendered into the dialog box's body.
            *title:* (optional) A title to appear at the top of the dialog box. If you want to omit a title but include classes, this argument can be an empty string (`''`).
            *classList:* (optional) A list of CSS classes to add to the dialog, for styling. The classes should be a space-separated list of quoted class names (i.e. `'class-a' 'class-b' 'class-c'`), a quoted list of space-separated class names (i.e. `'class-a class-b class-c'`), or one or more string arrays (i.e. `['class-a', 'class-b', 'class-c']`), or any combination of thereof.

        *Usage:*
        ```
        /% 
          creates a link that opens a dialog box called 'Character Sheet' 
          with the classes .char-sheet and .stats
          and renders the content of the passage 'charsheet' into it 
        %/
        <<link 'View Character Sheet'>>
          <<popup 'charsheet' 'Characer Sheet' 'char-sheet stats'>>
        <</link>>

        /% create an about button for your credits that uses the content of the 'credits-passage' passage %/
        <<button 'About'>>
          <<popup 'credits-passage' 'Credits'>>
        <</button>>
        ```
      parameters:
        - passage |+ string |+ ...string
    dialogclose:
      name: dialogclose
      parent:
        dialog
      description: |-
        *Syntax:* `<<dialogclose>>`
        
        Closes the dialog.
        
        *Usage:*
        ```
        <<link 'View Character Sheet'>>
          <<dialog 'Character Sheet' 'char-sheet stats'>>\
            |Strength|$str|
            |Dexterity|$dex|
            |Wisdom|$wis|\
          @@float:right;
            <<button "Close">><<dialogclose>><</button>>
          @@
          <</dialog>>
        <</link>>
        ```
    # end dialog api macros
    
    # start popover
    popover:
      container: true
    dismisspopover: {}
    # end popover
    
    # start ui
    ui: {}
    # end ui
    
    # start fading
    fadein:
      container: true
    fadeout:
      container: true
    # end fading
    
    # start css
    css: {}
    # end css
    
    # start notify
    notify:
      container: true
    # end notify
    
    # start meter macros
    newmeter:
      container: true
      children:
        - colors
        - sizing
        - animation
        - label
    colors:
      parents: 
        - newmeter
    sizing:
      parents: 
        - newmeter
    animation:
      parents:  
        - newmeter
    label:
      parents:  
        - newmeter
    showmeter: {}
    updatemeter: {}
    # end meter macros
    
    # start speech box system
    character:
      name: character
      description: |-
        *Syntax:* `<<character name [displayname] imageSrc>>`

        This macro associates a character name, which will automatically become a macro, with an image resourcem provided as a URL (can be relative or absolute). This macro is essentially a macro factory—it creates other macros based on the arguments you pass. This means that the `name` argument must therefore follow the parameters of normal macros: it must not contain spaces or special characters outside what macro names ordiarily allow. If you need character names without these limitations, you can use the `<<say>>` macro (see below).

        > [!DANGER] This macro will only function if run before the story starts, that is before the first passage is loaded. The `StoryInit` special passage is therefore the best place to define characters.

        If you want your character(s) to have definitions like this one you'll have to add them yourself. They are defined in `chapel.twee-config.yaml`, there's a comment describing the format to use a bit further down than the definition that created this current tooltip.

        *Arguments:*

          * `name`: a character name that can be used as a macro name. This is used to create a macro, and to fill in the name area on the generated speech box. The latter will be automatically capitalized, so if you pass `"lisa"`, the generated macro will be `<<lisa>>` and the name in the speech box will display as `Lisa`. If you pass `"Lisa"`, the name in the speech box will appear `Lisa`, but the macro will be `<<Lisa>>`.
          * `displayname` (optional) : if provided, will be displayed instead of the `name` in the speech box heading. This allows for naming such as `???` or `Maxine Delacroix`, which would otherwise be invalid due to being unable to be used as macro names.
          * `imageSrc`: a URL to an image resource to be used as a character portrait. Portraits should generally be taller than they are wide, as the name suggests, though squares will work fine. Large images will be shrunk to a reasonable size, butvery small images will not be enlarged to fit and may not look right.

        *Usage:*
        ```
        /* creating characters and associating them with images (goes in StoryInit) */
        <<character 'lisa' 'images/portraits/lisa.jpg'>>
        <<character 'bob' 'https://some.website.net/url/to/an/image_file.png'>>
        <<character 'billy' 'data:image/jpg;base64, [base64 encoded data]'>>
        <<character 'maxine' '???' 'images/portraits/unkown-person.jpg'>>

        /* using the generated macros in passages */
        <<lisa>>Hey there!<</lisa>>

        <<maxine>>Do i know you?<</maxine>>

        <<billy>>You just use the name you passed into the {{{<<character>>}}} macro as its own macro to create speech boxes!<</billy>>
        ```
      parameters:
        - string &+ string |+ string
    say:
      name: say
      container: true
      description: |-
        *Syntax:* `<<say name [imageSrc]>>...<</say>>`

        This macro can be used to create speech boxes that aren't based on predefined characters, allowing you to use names that would be unsuitable as macro names, use bit characters that aren't worth defining, or change a character's name or image, or use characters that don't have associated images.

        *Arguments:*

          * `name`: a character name that can be used in the text box.
          * `imageSrc`: (optional) a URL to an image resource to be used as a character portrait.

        *Usage:*
        ```
        <<say 'Lisa' 'images/portraits/lisa.jpg'>>Hey there!<</say>>

        /* without an image */
        <<say 'Some Guy'>>You n'wah!<</say>>
        ```
      parameters:
        - string |+ string
    ### You'll have to add your own character macros for the characters you create with <<character>> or setup.addCharacter()!

    ### Use this format:
    ### characterName:
    ###   name: characterName
    ###   container: true

    ### (Optional) If you for some reason want a description in the mouse-over tooltip you can add one to your character like it's done above in the say and character definitions.
    
    # end speech box system
    
    # start events
    on:
      container: true
      children:
        - which
    one:
      container: true
      children:
        - which
    event:
      container: true
      children:
        - which
      deprecated: true
      depecatedSuggestions:
        - on
        - off
    which:
      parents:  
        - on
        - off
        - event
    trigger: {}
    off: {}
    # end events
    
    # start continue
    cont:
      container: true
    ignore: {}
    # end continue
    
    # start swap
    swap:
      container: true
      children:
        - onswap
    onswap:
      parents:  
        - swap
    resetswap: {}
    # end swap
    
    # start mouse events
    mouseover:
      container: true
      children:
        - onmouseover
        - onhover
        - onmousein
        - onmouseenter
        - onmouseout
    onmouseover:
      parents:  
        - mouseover
    onhover:
      parents:  
        - mouseover
    onmousein:
      parents:  
        - mouseover
    onmouseenter:
      parents:  
        - mouseover
    onmouseout:
      parents:  
        - mouseover
    # end mouse events
    
    # start message
    message:
      container: true
    # end message
    
    # start typesime
    typesime:
      container: true
    # end typesime
    
    # start pronouns
    pronouns: {}
    verb: {}
    # end pronouns
    
    # start articles
    a: {}
    an: {}
    A: {}
    An: {}
    setarticle: {}
    # end articles
    
    # start preload
    preload: {}
    # end preload
    
    # start done
    done:
      container: true
    # end done
    
    # start file system
    import: {}
    export: {}
    # end file system
    
     # start first
    first:
      container: true
      children:
        - then
        - finally
    then:
      parents:  
        - first
    finally:
      parents:  
        - first
    # end first
    
    # start disable
    disable:
      container: true
    # end disable