diff --git a/chapel.twee-config.yaml b/chapel.twee-config.yaml index 5bddb3d..812f8b3 100644 --- a/chapel.twee-config.yaml +++ b/chapel.twee-config.yaml @@ -3,15 +3,287 @@ sugarcube-2: macros: # start simple inventory - newinventory: {} - pickup: {} - drop: {} - dropall: {} - clear: {} - transfer: {} - sort: {} - inventory: {} - linkedinventory: {} + newinventory: + name: newinventory + description: |- + *Syntax:* `<>` + + 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 <> 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 %/ + <> + + /% create an inventory in the $playerInventory variable and place two items in it %/ + <> + + /% create an inventory for the kitchen room and call it $kitchenInventory and place some items in it %/ + <> + + /% create a suit case called $suitCase always contains a key, but also includes some random items %/ + <> + <> + ``` + parameters: + - string |+ ...text + pickup: + name: pickup + description: |- + *Syntax:* `<>` + + The `<>` 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 `<>` 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 %/ + <> + + /% you may wish to check if the player already has the item: %/ + @@#link; + <> + <> + <>You already have a gun, you don't need another...<> + <> + <> + <>You take the gun and hide it in your coat.<> + <> + <> + @@ + + /% you can also add several items at once %/ + You received your inheritance! + <> + <> + + /% unique items: %/ + :: StoryInit + <> + + :: A Later Passage + <> + /% only shield is added %/ + + :: Some Other Passage + /% however, be warned: %/ + <> + /% + 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:* `<>` + + The `<>` 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 `<>` 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 %/ + <> + + /% have a random item stolen %/ + <> + <> + + /% drop all weapons %/ + :: StoryInit + <> + <> + + :: Prison + The guards frisk you and take your weapons. + <> + /% drops any item from _weaponList, if present %/ + ``` + parameters: + - string &+ ...text + dropall: + name: dropall + description: |- + *Syntax:* `<>` + + The `<>` macro removes all items from the inventory indicated by the $variable. The `<>` 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 `<>` or the `Inventory()` constructor. + + *Usage:* + ``` + /% clears the inventory %/ + <> + ``` + parameters: + - string + clear: + name: clear + description: |- + *Syntax:* `<>` + + The `<>` macro removes all items from the inventory indicated by the $variable. The `<>` 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 `<>` or the `Inventory()` constructor. + + *Usage:* + ``` + /% clears the inventory %/ + <> + ``` + parameters: + - string + transfer: + name: transfer + description: |- + *Syntax:* `<>` + + The `<>` 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 `<>` and `<>`, but has a few benefits over doing it that way. For one, if you were to <> an item from one inventory and have another `<>` the same item, you run the risk of having the reveiving inventory getting an item that the first inventory never had, since `<>` does nothing if the item doesn't exist. Using `<>`, if an item isn't present in the first inventory, the second inventory will not receive said item. Like `<>` 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 `<>` 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 %/ + <> + <> + <> + + /% transfer weapons, so the player can get them back %/ + :: StoryInit + <> + <> + <> + + :: Prison + The guards frisk you and take your weapons. + <> + + :: Release + You've been released from prison, and your weapons are returned to you. + <> + ``` + parameters: + - string string ...text + sort: + name: sort + description: |- + *Syntax:* `<>` + + The `<>` 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 `<>` or the `Inventory()` constructor. + + *Usage:* + ``` + <> + ``` + parameters: + - string + inventory: + name: inventory + description: |- + *Syntax:* `<>` + + The `<>` 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 `<>` 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: + ``` + <> /% or just <> if the default strings aren't changed %/ + ``` + Result: + ``` + wallet + keys + phone + pocket knife + candy bar + ``` + Example: + ``` + <> + ``` + Result: + ``` + wallet, keys, phone, pocket knife, candy bar + ``` + Example: + ``` + <> + <> + ``` + Result: + ``` + candy bar - keys - phone - pocket knife - wallet + ``` + parameters: + - string |+ string + linkedinventory: + name: linkedinventory + description: |- + *Syntax:* `<>` + + The `<>` 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 `<>` 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 `<>` 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 `<>` or the `Inventory()` constructor. + + *Usage:* + ``` + /% containers %/ + You open the box. Want to take anything with you? + <> + + /% let the player drop items %/ + <> + + /% let the player place items %/ + You open the closet. Lots of space in here. + <> + ``` + parameters: + - string &+ string |+ string # end simple inventory # start cycles system @@ -32,18 +304,143 @@ sugarcube-2: # start dialog api macros dialog: + name: dialog container: true children: - onopen - onclose + - dialogclose + description: |- + *Syntax:* `<> <>` + + The `<>` 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 `<>` and `<>` 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 %/ + <> + <>\ + |Strength|$str| + |Dexterity|$dex| + |Wisdom|$wis|\ + <> + <> + + /% create an about button for your credits %/ + <> + + /% a dialog with no title or classes %/ + <> + <>Greetings!<> + <> + ``` + parameters: + - (|+ string |+ ...string) onopen: - parents: + name: onopen + container: true + parents: - dialog + description: |- + You can use this child tag to run code when the dialog is opened. + + *Usage:* + ``` + <> + <>\ + |Strength|$str| + |Dexterity|$dex| + |Wisdom|$wis|\ + <> + <> + <> + ``` onclose: - parents: + name: onclose + container: true + parents: - dialog - popup: {} - dialogclose: {} + description: |- + You can use this child tag to run code when the dialog is closed. + + *Usage:* + ``` + <> + <>\ + |Strength|$str| + |Dexterity|$dex| + |Wisdom|$wis|\ + <> + <> + <> + ``` + popup: + name: popup + description: |- + *Syntax:* `<>` + + The `<>` macro provides a similar result to what you might get by pairing a `<>` macro and an `<>` macro. + The macro is generally the same as `<>`, 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 `<>` and `<>` feature; if you need it, use the `<>` macro with `<>`. + + *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 + %/ + <> + <> + <> + + /% create an about button for your credits that uses the content of the 'credits-passage' passage %/ + <> + ``` + parameters: + - passage |+ string |+ ...string + dialogclose: + name: dialogclose + parent: + dialog + description: |- + *Syntax:* `<>` + + Closes the dialog. + + *Usage:* + ``` + <> + <>\ + |Strength|$str| + |Dexterity|$dex| + |Wisdom|$wis|\ + @@float:right; + <> + @@ + <> + <> + ``` # end dialog api macros # start popover @@ -97,13 +494,70 @@ sugarcube-2: # end meter macros # start speech box system - character: {} + character: + name: character + description: |- + *Syntax:* `<>` + + 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 `<>` 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 `<>` 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 `<>`. + * `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) */ + <> + <> + <> + <> + + /* using the generated macros in passages */ + <>Hey there!<> + + <>Do i know you?<> + + <>You just use the name you passed into the {{{<>}}} macro as its own macro to create speech boxes!<> + ``` + parameters: + - string &+ string |+ string say: + name: say container: true - ### you'll have to add your own character macros! use this format: - + description: |- + *Syntax:* `<>...<>` + + 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:* + ``` + <>Hey there!<> + + /* without an image */ + <>You n'wah!<> + ``` + parameters: + - string |+ string + ### You'll have to add your own character macros for the characters you create with <> 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 diff --git a/docs/dialog-api-macro-set.md b/docs/dialog-api-macro-set.md index 979cf74..ae663d5 100644 --- a/docs/dialog-api-macro-set.md +++ b/docs/dialog-api-macro-set.md @@ -83,7 +83,7 @@ You can use this child tag to run code when the dialog is closed. **Syntax**: `<>` -The `<>` macro provides a similar result to what you might get by pairing a `<>` macro and an `<>` macro. The macro is generally the same as `<>`, 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 macr does not support the `<>` and `<>` feature; if you need it, use the `<>` macro with `<>`. +The `<>` macro provides a similar result to what you might get by pairing a `<>` macro and an `<>` macro. The macro is generally the same as `<>`, 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 `<>` and `<>` feature; if you need it, use the `<>` macro with `<>`. **Arguments**: