Hi gang!

Editorial

It has been a while since I last wrote an article, and since I'm a little bored while waiting for someone else to come online I figured that since I have Minecraft open anyway I might as well dump something in here again. Maybe also good to know: although my story is fully based on the current version of 1.13 (it's kind of hard to go back to 1.12.2 after you became more familiar with it) every example I share will also be usable on 1.12.2. It's easy: just move the JSON part around.

Three important things to keep in mind:

• I expect you to be familiar with commands. If not then maybe this blog getting started with command blocks will help you get started on the basics.
  
• I strongly suggest that you make yourself a datapack to put all the code in. This will make it much easier to use your collection within other worlds. Of course command blocks also work to get started.
  
• Use a text editor such as notepad! Especially with longer commands, this can make it much easier to cut the command into smaller parts.
  

Books in Minecraft

One of the things I really enjoy about Minecraft is that it is such a diverse game. A classic issue of many small things can lead up to one bigger thing. For example books... Get a piece of leather (you can get some from killing cows) and combine that with three paper (which you can get from three sugarcane) and you can craft yourself a book. By itself this isn't very useful. But if you combine it with some wooden planks you can build yourself a bookshelf which can help you enhance an enchantment table.

And of course there's also the recipe which hints back at medieval times: if you combine your book with a feather (which you can get from killing chickens) and an inksac (which is dropped by squids) then you can craft a 'Book and Quill', also known as a writable book.

It's pretty cool: you can write text, save it and eventually sign your book so that you get a story which everyone will be able to recognize as something that you wrote. As you can see in the title picture my friend sometimes uses books to tell me their "wish for the day" (long story ;)).

Books by themselves are fun, but still somewhat limited. You can't easily add color of formatting to the text you write. Fortunately there are some nice tricks for that though: by using the paragraph character § (you can make this using the alt-21 combination (so: press alt and keep it pressed, then type 21 on your numerical keyboard)). When you use this character in a book then Minecraft will pick this up as a formatting code. This Minecraft wiki page gives you a good overview of those. And that allows you to actually use color and formatting within books. The only caveat: you'll have to copy & paste your text in. So write text within an editor such as notepad, and then copy it in.

But did you know that you can also 'program' books (I prefer the term scripting myself though)?

Items and properties (small recap)

Although I definitely recommend to read up on my other earlier mentioned blog if you haven't already here's a quick recap... Many items within Minecraft have properties assigned to them. These properties store values using the so called NBT format and you can specify these properties using JSON formatting. Just think of those as a series of values which help define whatever object it is you're working on.

For example, to give yourself a diamond sword named 'slasher' you'd use the following command:

/give @p minecraft:diamond_sword{display:{Name:"\"Slasher\""}}

So: <command> <item>{nbt properties}. The NBT section uses JSON formatting which means that the section is made up from parts. The display:{} section contains properties which apply to the look of the item, such as its name. We can recognize Name as a property because it's capitalized (this isn't always the case though). Why the double use of quotes and the backslashes? Because as of 1.13 Name expects so called strict JSON formatting. Name is a string so it expects quotes around the name. And because we already used quotes to specify the property value within our command we had to use another set of quotes. The problem with that is that Minecraft could mistake the next pair of quotes as the closing pair. That's why we use \ to tell Minecraft that it needs to treat the next pair literally. So basically to ignore it (at least for now).

This may seem like a lot of bother, and I agree, but there's actually a good reason to do it this way: it allows us to add properties and formatting to the name. Do you want a sword with a red name and without the use of italics (which get applied automatically the moment you rename an item)?

Couldn't be easier, though it'll be a bit more typing:

/give @p minecraft:diamond_sword{display:{Name:"{\"text\":\"Slasher\",\"color\":\"red\",\"italic\":false}"}}

This is what strict JSON looks like: all properties and their values are encapsulated in quotes (as long as we're dealing with String values) and the entire section is defined as a compound (so: within curly brackets). And because Name expects a string that too is surrounded by quotes (and the main reason we need to use those backslashes again).

It may look very complex at first but it really isn't: it's just a collection of properties (text, color and italic) which are grouped together using {} and which all have a specific value. This is why I suggest using a text editor (such as notepad) so that you can cut the command up into smaller parts, which may make it easier to follow:


/give @p minecraft:diamond_sword{

display:{

Name:"

{\"text\":\"Slasher\",\"color\":\"red\",\"italic\":false}

"
}
}

See what I did here? You can even split it up even further if you want to. Just remember that it's safer to re-assemble the whole lot before you paste it into Minecraft (though this example would work if you'd just copy & pasted it).

Why all this dry theory you ask? Simple really: because books aren't that much different from this.

Scripting a book

Somewhere above I mentioned two book types: the regular book and the Book and Quill (which is also known as a writable book). There's actually one more type available to us: the written book ("minecraft:written_book"). If you have a writable book and sign it then the item will change into a written book.

And just like any other item in the game this one has NBT properties which we can define using a JSON formatted section. The only problem is that we might need to write up quite a lot. There's actually some nice trickery going on here.

But first things first: what properties can we use anyway? Well... The easiest way to find out is to simply write a book ourselves and then use the /data command on it:

• /give @p minecraft:writeable_book
  
• <write some text in it & sign it>
  
• /data get entity @p Inventory
  

So what do we have here...

• author: this is obviously the player (or entity?) who actually wrote the book.
  
• title: every book needs a title and this isn't any different.
  
• pages: this is where things become a little more complicated :)
  
• generation: not shown in the screenshot, but this property keeps track of how many times a book has been copied. 0 (or not specified) indicates an original book. 1 specifies a 'copy of original' and 2 specifies a copy of a copy (which cannot be copied any further).
  

A list of pages

This is where things become complex really fast. Once again: it's not so much the complexity of the formatting but the sheer volume of it all. In no time you'll find yourself dipped into a sea of double quotes, back slashes, compounds, strict JSON and then we haven't even addresses the actual contents of the book yet!

A book is made up of pages. Sounds logical. And to specify these we have to use the pages property which is actually a list (that's why the block quotes '[]' are used). As you can see in the screenshot above a page is basically a string of text but set up using strict JSON formatting. Fortunately for us this doesn't mean that we'll always have to specify every little detail. Remember my example with the diamond sword and its name above?

We can do the exact same thing for books.

Let's script a book which warns our players that we'll be too busy with books for a while so we have no time for their problems right now ;)


/give @p minecraft:written_book{

author: "The admin",
title: "Busy with books!",
generation: 1,
pages:["
\"Please be patient, I'm too busy with this book right now! ;)\"
"]
}

As before I simply cut up our command into smaller parts, but I urge you to pay special attention to the pages section. See what I did there? I didn't bother with difficult strict JSON stuff such as specifying text, color and other properties. I simply fed Minecraft a string surrounded with quotes. As a result we now have one page of our book.

Want to add a second page? Couldn't be easier:


/give @p minecraft:written_book{

author: "The admin",
title: "Busy with books!",
generation: 1,
pages:["
\"Please be patient, I'm too busy with this book right now! ;)\"
","
\"ps: if you're still reading this, why not check out my blog on Planet Minecraft?\"
"]
}

See what I mean? This is also what i meant with that sea of quotes and such earlier: because this could be a bit confusing at first. You need to keep in mind that 'pages' is a list of strings which make up the pages. Because it is a string it needs quotes to keep the stuff together.

And the opening quote, so the beginning of page one, happens right after the pages:[ definition. That's why I need a closing quote and a new opening one in between (the "," section).

I hope you can agree with me that this makes scripting books pretty easy. Just be careful about keeping track of your opening and closing quotes, and be sure to use the proper escapes (so a backslash) whenever needed.

Now, this is fine and all but also pretty boring if you ask me.

Some fun with strict JSON

The problem is that you can do tons of cool stuff with strict JSON, applying formatting properties is only a small part of it. So why aren't we using that?

For example... I mentioned my PMC blog in that book, I obviously refer to this blog, so why don't we make it easier on the reader and allow them to click on the text in order to go to this blog? Sounds impossible? It's not. All we need is to define a so called actionEvent. It consists of 2 properties: action and value. The first specifies the action (duh!) and the second provides additional information for it. Some useful actions:

• open_url (gee, I wonder what this would do? ;) )
  
• run_command (runs the given command after you clicked it)
  
• suggest_command (copies the given command to the players chat without activating it)
  
• change_page (cool for books: flips the book to a given page)
  

However, we're also going to run into a problem. See: the pages property defines a list of pages. Yet what we need to do is cut up our page so that only the "my blog on Planet Minecraft" section can be clicked on. We can't just dump a comma in there, that would only define the next page.

The solution? Simple: define our page as a new list. So: create a list within the list ;)


/give @p minecraft:written_book{

author: "The admin",
title: "Busy with books!",
generation: 1,
pages:["
\"Please be patient, I'm too busy with this book right now! ;)\",
","
[
\"ps: if you're still reading this, why not check out my blog on Planet Minecraft?\",
\"(just click the link to go there!)\"
]
"]
}

There is a chance that PMC will cut out some characters (I just noticed a '[' disappearing, annoying as heck) but just imagine the opening in there if it isn't. u]This[/u] is how you cut up a page. Notice how I can now easily use a comma and then define a new (strict) JSON based string for another page section?

So let's take this slowly... Step one is to 'convert' "my blog on Planet Minecraft" into an officially set up strict JSON definition:


/give @p minecraft:written_book{

author: "The admin",
title: "Busy with books!",
generation: 1,
pages:["
\"Please be patient, I'm too busy with this book right now! ;)\",
","

\"ps: if you're still reading this, why not check out \",
{\"text\":\"my blog on Planet Minecraft?\"}

]
"]
}

So now that we have defined our separate text component (that's the official name) let's add that clickEvent property:


/give @p minecraft:written_book{

author: "The admin",
title: "Busy with books!",
generation: 1,
pages:["
\"Please be patient, I'm too busy with this book right now! ;)\",
","
[
\"ps: if you're still reading this, why not check out \",
{\"text\":\"my blog on Planet Minecraft?\",
clickEvent:{\"action\":\"open_url\",\"value\":\"https://www.planetminecraft.com/blog/multipart-guide-converting-your-world-from-1-12-to-1-13/\"}}

]
"]
}

Now, this is fun and all but there's yet another problem: nothing in that book will stand out. So how should the reader know that they can click on that text to visit my blog? We need to tell them!


/give @p minecraft:written_book{

author: "The admin",
title: "Busy with books!",
generation: 1,
pages:["
\"Please be patient, I'm too busy with this book right now! ;)\",
","
[
\"ps: if you're still reading this, why not check out \",
{\"text\":\"my blog on Planet Minecraft?\",
clickEvent:{\"action\":\"open_url\",\"value\":\"https://www.planetminecraft.com/blog/multipart-guide-converting-your-world-from-1-12-to-1-13/\"},
hoverEvent:{\"action\":\"show_text\",\"value\":{\"text\":\"Click to open my blog!\",\"color\":\"aqua\",\"italic\":true}}

}
]
"]
}

I suppose you could also use other tricks, for example underlining the text or maybe make it italic, but that's something you'll have to decide for yourself ;)



But as you can see it's actually decently simple to make a book like this. All it takes is making sure that you use the right components and that you don't mix up things such as opening and closing quotes (and brackets).

Books have limitations!

One very important thing to keep in mind when you're going to use books is that they are fully "as-is". For example: if you create a book which contains all sorts of destinations to teleport yourself too but the reader doesn't have access to the /tp command then this won't work for them. Simply because all the book does is help you to execute a command, it does not circumvent any protection schemes (which a command block could do).

Even so, they can be lots of fun to script (at least I think so) and there's tons you can do with them (this is really only the tip of the figurative iceberg so to speak). You can even personalize books if you want to (using the selector property) so that it will show the name of the reader (small warning: the name would be determined from the player who first opens the book, so don't expect something to change every time another player opens the book).

And there you have it!

Who needs generators when you can easily open up notepad and type in a few commands yourself?