create custom text box message syntax

[briaguya-ai]

there are plenty of places where we are using custom text (gossip stone hints, randomizer specific items, skulltula text)

even with #831, we have a mix of characters being used to control the text (& for newline, ^ for new box, %g for green text, etc.) and hardcoded message controls such as \x12\x38\x82\ for icons and sounds)

ideally we'd have a way to create custom text boxes where anyone can read the string and understand what's happening, without needing to understand hex control codes.

what is the background? (wooden/blue/etc.), do we have a/what is the item icon? where are newlines/new boxes? when does the text color change (#737)? are there sounds associated? are there options (do we need to make these into json objects instead of just strings?)

ideally, someone looking through a randomizer spoilerfile with hints in it could understand what each hint is doing with the text box, while giving the hint author enough flexibility to create any type of text box.

[leggettc18]

The background and position are currently handled outside the text itself (and it is this way in the base game as well). That part I think makes sense, see this line from PR 831 for an example of where this would be useful. Here we are looping over a set of messages that should all have the same textbox position and type.

Currently for messages that have item Icons in them, I have CreateGetItemMessage, which takes an itemID as an argument and uses that to add the icon corresponding to that itemID to the beginning of each page of the custom text box. However, this does not work for the Altar Text, as it has a different icon at the beginning of each page (and possibly pages with no icons at all).

Personally, I kind of like the idea of using the syntax from the Non-JP Dev Files column from the Control Codes table from the Text Format page on CloudModding OoT Wiki. It's already documented, the only issue is we have to come up with a newline syntax since that's the one control code that is missing from here. That should be relatively easy though, just have to pick a symbol that isn't in use already, like | or >

[briaguya-ai]

one of the main reasons i'm opposed to using those control codes is the reliance on ids

examples:

the one place where the ids make sense imo is

but even there we'd run into the issue of that assuming there's only 1 message table (which is no longer the case with #831)

i'd prefer to be able to use named colors/sound effects/icons/backgrounds

[leggettc18]

That is a good point. We'll either need to be OK with string concatenation (so I can expose some helper functions and do something like "..." + ICON(iconID) + "..."), expect people to use some variant of printf, have some way to parse a string literal into an enum, or have a map from string literal icon names to IDs (or maybe even the textures themselves and add hooks into DrawMessage?). The last option seems the most flexible when it comes time to let mods add custom textures, but I don't want to prematurely optimize for that when we aren't really sure exactly what it will look like.

[leggettc18]

Seems like in the situation where you need conversions from strings to enums, an unordered_map seems to be the standard solution. With that in mind, I propose the following.

• Create an enum for sound effects, if one does not already exist (I think there may be some kind of #defines already but not sure if these are all safe for use in textboxes or not).
• Create two unordered_maps with string literals as the keys and Enums as the values, one for Sound Effects and one for Item Icons.
• Add the ability in FormatCustomMessage to recognize some kind of syntax surrounding the string representing the enum value in the text, substring the enum string, pull the enum value from the table, and replace the entire surrounding syntax and enum string with the proper control code using the enum value.
• As for the surrounding syntax, I like the idea of either ${IconName} for icons and #{SoundName} for sounds, or {IconName} for icons and [SoundName] for sounds. 50/50 on which one I like more.

Advantage of this approach is that if we want to change the string-to-enum maps into string-to-icon/string-to-sound maps later, we don't need to update the strings themselves to accommodate that change, just the maps and the parsing code. Disadvantage is that this requires more string-literal matching, but I don't see much of a way around that here. And we can provide fallbacks if something doesn't match in game so there's at least no crash, either by not drawing an icon or drawing the SOLD OUT icon instead or something like that.

[briaguya-ai]

@leggettc18 re: json objects

instead of doing new page/box with a character, we could have each box be a different string (or object)

so maybe something like this

{
  [
    {
      "icon": "Goron Ruby",
      "text": "this is where the ruby is"
    },
    {
      "icon": "Forest Medallion",
      "text": "this is where the forest medallion is"
    },
    "this is a line of text without any special icons or other stuff"
  ]
}

not sure if that's a good idea or not but that's what i was thinking

[leggettc18]

OK, so you're saying that whole json block is one message, and each element of the array inside is a page (as in ends with the wait-for-input control code)? I like the idea but it's quite verbose, especially when it comes to having different languages, as we'd need three (or more) of those arrays since the different languages don't necessarily match up.

Also this would be for mods/spoilerfiles right? Like they would provide their text in a json file? Because I was imagining having this whole thing as a string literal where randomizer.cpp is currently adding it's custom messages and it was feeling really verbose and weird to put this in as a string literal, parse it into a json object, immediately read from it back into the CustomMessageEntry to save in the table...

[briaguya-ai]

I like the idea but it's quite verbose,

that's my feeling about it as well, i like it because it's structured, but it would lead to pretty big files

Also this would be for mods/spoilerfiles right? Like they would provide their text in a json file?

yeah, that's what i was thinking. i know for hints we already do string generation and then put it into the json, so i was thinking generating json there wouldn't be bad. i see your point about the other string literals though, not sure what the best way to handle those would be

[leggettc18]

Having both is also an option. Have the usual methods we have now for the hardcoded strings and an ImportJson method or some such. We can still share the special character replacement, coloring syntax, and probably a few other things between both. The hardcoded method will need additional syntax for things that the JSON would handle based on the structure like icons and box breaks, but at that point I actually feel like the string concatenation with helper methods that return the control codes would be fine rather than any string replacement syntax.

[briaguya-ai]

string concatenation with helper methods that return the control codes

And we could call into those when doing json parsing

[leggettc18]

At that point it sounds like the only things we still need to decide are what syntax to use for newlines and colors.

[leggettc18]

Yeah after thinking it over for the past few days I'm definitely on board with the JSON objects as the preferred syntax for mods (mod developers supply a json file, either raw or as part of the OTR, mods being OTR archives was the plan right?). And stuff like randomizer that's hardcoded in gets the string concatenation with helper methods option. The JSON structure can have keys for choices, icons, sound effects (or can those happen in the middle of a text box?), background (if changing between textboxes), and can actually probably handle newlines if we have the text key as an array. Theoretical expansion of your syntax with choices, gotos, sounds, and newlines as an example.

{
  [
    {
      "icon": "<icon_name>",
      "sound": "<sound_effect_name>",
      "text": [
        "this is one line of text."
        "this is another line."
        "Do you understand?"
      ],
      "choice": {
        "option-one": { 
          "text": "Yes",
          "goto": <new-text-id>
        },
        "option-two": { 
          "text": "No",
          "goto": <current-text-id>
        }
      }
    },
    {
      "text": [
        "this is a text box",
        "with only text, no icons"
        "or sound effects or anything."
      ]
    }
  ]
}

We would still need some kind of syntax for things that can happen anywhere in the text, like colors, player name, skulltula count, etc. If we want to be clear but verbose, I think a bracket syntax of some kind could actually work for that (i.e. some variable name surrounded in brackets, like {PlayerName} or [SkulltulaCount]. As for which brackets/surrounding characters to use and which casing style (Camel vs Pascal, etc) I don't have any particular preference for. Also open to other ideas as well.

[garrettjoecox]

+1 for brackets for variables {{}} or {}

[aMannus]

This isn't specifically ONLY for rando, but I'm adding it to the v3 rando milestone for now, as that's likely why this would be picked up in the first place.

[briaguya-ai]

thinking about syntax for things that can happen anywhere in text, we could have simple things like

"{blue}i'm blue{white} da ba dee"

but also possibly support an object type syntax in there

"this is a message{controlCode: '@03'}"

or something