From 3b5f94ff2d2bb92c9537a34d722bf708c4feba44 Mon Sep 17 00:00:00 2001 From: Haley Scribe <82309147+HaleyScribe@users.noreply.github.com> Date: Sun, 11 Apr 2021 18:57:22 +0200 Subject: [PATCH 1/8] Fix typo. --- docs/dialog-api-macro-set.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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**: From e026fb82383a67f3a58dad58e6642538b0b54db4 Mon Sep 17 00:00:00 2001 From: Haley Scribe <82309147+HaleyScribe@users.noreply.github.com> Date: Sun, 11 Apr 2021 19:00:20 +0200 Subject: [PATCH 2/8] More detailed custom macro definition for T3LT. Macro set: dialog-api-macro-set. --- chapel.twee-config.yaml | 135 ++++++++++++++++++++++++++++++++++++++-- 1 file changed, 131 insertions(+), 4 deletions(-) diff --git a/chapel.twee-config.yaml b/chapel.twee-config.yaml index 5bddb3d..7d6da7f 100644 --- a/chapel.twee-config.yaml +++ b/chapel.twee-config.yaml @@ -31,19 +31,146 @@ sugarcube-2: # end playtime system # start dialog api macros +sugarcube-2: + 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 From 821ad69d54ca9e6427ec30cc93cd8aa99a584c34 Mon Sep 17 00:00:00 2001 From: Haley Scribe <82309147+HaleyScribe@users.noreply.github.com> Date: Sun, 11 Apr 2021 19:49:29 +0200 Subject: [PATCH 3/8] More detailed custom macro definition for T3LT. Macro set: speech-box-system. --- chapel.twee-config.yaml | 63 +++++++++++++++++++++++++++++++++++++++-- 1 file changed, 60 insertions(+), 3 deletions(-) diff --git a/chapel.twee-config.yaml b/chapel.twee-config.yaml index 7d6da7f..940166f 100644 --- a/chapel.twee-config.yaml +++ b/chapel.twee-config.yaml @@ -224,13 +224,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 # FIXME: I'm not sure how to make the displayName argument optional here and still require the icon argument so both are optional for now. 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 From 69af10670d645cab3ccf7d24db5de11190284128 Mon Sep 17 00:00:00 2001 From: Haley Scribe <82309147+HaleyScribe@users.noreply.github.com> Date: Sun, 11 Apr 2021 20:55:17 +0200 Subject: [PATCH 4/8] More detailed custom macro definition for T3LT. Macro set: simple-inventory. --- chapel.twee-config.yaml | 289 ++++++++++++++++++++++++++++++++++++++-- 1 file changed, 280 insertions(+), 9 deletions(-) diff --git a/chapel.twee-config.yaml b/chapel.twee-config.yaml index 940166f..5ab3d74 100644 --- a/chapel.twee-config.yaml +++ b/chapel.twee-config.yaml @@ -3,15 +3,286 @@ 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 |+ 'unique' |+ ...text # FIXME: I'm not sure how to make 'unique' optional here and still require the itemList argument so both are optional for now. If this doesn't get fixed, maybe add a note about it in the description so users can be aware of it. + 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 From 1f9090996ffd4640ff30546e2d94e67b81188eae Mon Sep 17 00:00:00 2001 From: Haley Scribe <82309147+HaleyScribe@users.noreply.github.com> Date: Sun, 11 Apr 2021 20:59:47 +0200 Subject: [PATCH 5/8] Copy recommendation part of FIXME comment from my latest commit for simple-inventory to the similar FIXME comment in the speech-box-system section. --- chapel.twee-config.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/chapel.twee-config.yaml b/chapel.twee-config.yaml index 5ab3d74..52cac6a 100644 --- a/chapel.twee-config.yaml +++ b/chapel.twee-config.yaml @@ -528,7 +528,7 @@ sugarcube-2: <>You just use the name you passed into the {{{<>}}} macro as its own macro to create speech boxes!<> ``` parameters: - - string |+ string |+ string # FIXME: I'm not sure how to make the displayName argument optional here and still require the icon argument so both are optional for now. + - string |+ string |+ string # FIXME: I'm not sure how to make the displayName argument optional here and still require the icon argument so both are optional for now. If this doesn't get fixed, maybe add a note about it in the description so users can be aware of it. say: name: say container: true From aa94ac27386713ba72923286be49444ae26f47cb Mon Sep 17 00:00:00 2001 From: Haley Scribe <82309147+HaleyScribe@users.noreply.github.com> Date: Sun, 11 Apr 2021 23:02:25 +0200 Subject: [PATCH 6/8] Fix the FIXME comments about optional arguments in the middle. --- chapel.twee-config.yaml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/chapel.twee-config.yaml b/chapel.twee-config.yaml index 52cac6a..9902796 100644 --- a/chapel.twee-config.yaml +++ b/chapel.twee-config.yaml @@ -85,7 +85,8 @@ sugarcube-2: %/ ``` parameters: - - string |+ 'unique' |+ ...text # FIXME: I'm not sure how to make 'unique' optional here and still require the itemList argument so both are optional for now. If this doesn't get fixed, maybe add a note about it in the description so users can be aware of it. + - string &+ ...text + - string &+ 'unique' &+ ...text drop: name: drop description: |- @@ -528,7 +529,7 @@ sugarcube-2: <>You just use the name you passed into the {{{<>}}} macro as its own macro to create speech boxes!<> ``` parameters: - - string |+ string |+ string # FIXME: I'm not sure how to make the displayName argument optional here and still require the icon argument so both are optional for now. If this doesn't get fixed, maybe add a note about it in the description so users can be aware of it. + - string &+ string |+ string say: name: say container: true From 83929129925040bd34fd84d7e1d71de2a299b1f7 Mon Sep 17 00:00:00 2001 From: Haley Scribe <82309147+HaleyScribe@users.noreply.github.com> Date: Mon, 12 Apr 2021 14:55:08 +0200 Subject: [PATCH 7/8] Remove accidentally copied lines from my original file. --- chapel.twee-config.yaml | 2 -- 1 file changed, 2 deletions(-) diff --git a/chapel.twee-config.yaml b/chapel.twee-config.yaml index 9902796..9c17e88 100644 --- a/chapel.twee-config.yaml +++ b/chapel.twee-config.yaml @@ -303,8 +303,6 @@ sugarcube-2: # end playtime system # start dialog api macros -sugarcube-2: - macros: dialog: name: dialog container: true From 02c1a3cdef45a23a1969b5b8ede186d9f4de5d2f Mon Sep 17 00:00:00 2001 From: Haley Scribe <82309147+HaleyScribe@users.noreply.github.com> Date: Mon, 12 Apr 2021 15:01:56 +0200 Subject: [PATCH 8/8] Fix types in parameter definitions. --- chapel.twee-config.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/chapel.twee-config.yaml b/chapel.twee-config.yaml index 9c17e88..812f8b3 100644 --- a/chapel.twee-config.yaml +++ b/chapel.twee-config.yaml @@ -119,7 +119,7 @@ sugarcube-2: /% drops any item from _weaponList, if present %/ ``` parameters: - - string & ...text + - string &+ ...text dropall: name: dropall description: |- @@ -283,7 +283,7 @@ sugarcube-2: <> ``` parameters: - - string & string |+ string + - string &+ string |+ string # end simple inventory # start cycles system