A description of text formatting

text-formatting.md

Text Formatting

What are the goals?

• A format that is easy for server admins to configure
• A format that is familiar to people dealing with text/easy to learn
• A format that is extensible and has the power to configure text objects in any way possible

Variables

Specifying variables is done with a standard "template" format, like so:

{name} went to {place} to eat {food}

When the text formatter replaces these variables, it inserts text into them, creating an object much like this one:

{
  children: [
    { text: "MyPlayer" }, // <-- text object where {name} goes
    { text: " went to "}
    { text: "MyPlace" }, // <-- text object where {place} goes
    { text: " to eat "}
    { text: "MyFood" }, // <-- text object where {food} goes
   ]
}

This means that any formatting on the inserted text objects stays only on them, and does not spill over to other parts of the source.

The syntax for variables should mostly follow the "new style" python template syntax as specified here.

Colors and Style

I haven't been able to find any better syntax to specify color sand style than the legacy syntax. However, we modify it a little bit to make it easier to use and read.

If you want to specify a color, use & and then the color name like so:

&{red}{name}&{grey} went to &{dark_blue}{place}&{grey} to eat &{green}{food}

In order to "close" a format like italics or underline, suffix "/" after the name. These pairs do not have to be perfectly nested as the format is calculated left to right, like so:

&{italics}&{bold}MyPlayer&{italics/} went to &{underline}MyPlace&{underline/} ...

As a shorthand you can use &/ to close the most recently configured format. This is the equivalent of the above:

&{italics}&{bold}MyPlayer&{italics/} went to &{underline}MyPlace&/ ...

We did not use &/ when closing the italics, as the most recently configured format was &{bold}.

If it is preferred, the brackets can be taken off a &{} statement:

&italics&boldMyPlayer&italics/ went to &underlineMyPlace&/ ...

I am not sure if formatting codes should be provided as an additional shorthand. On one hand it is shorter and less to type (and potentially more readable to some people). On the other hand the formatting codes have been deprecated and the full color format is more straightforward.

Advanced Text Options

The &{myformat} syntax is actually a shorthand for the text option format which is able to specify all of text's options as lenient Mojangson. This means that a color use like:

&{red}hello

desugars into:

&{color:red}hello

This means that you can do stuff like:

&{color:blue,bold:true,clickEvent:{action:open_url,value:'https://google.com'}}
Open google

To "close" text configured in this way, use the control &/:

&{color:blue,bold:true,clickEvent:{action:open_url,value:'https://google.com'}}
Open google
&/ other text

Possible directions to go in

Perhaps Mojangson should be deprecated in favor of a more declarative way to configure advanced options, like so:

&{blue}&{bold}&{openUrl 'https://google.com'}

This would open up the door for more advanced text formatting like so:

&{openUrl {my_url}}

Or for scoreboards:

&{scoreName *, scoreObjective 'obj'}

etc.

You're missing quotes around the keys in your JSON examples.