Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Chapter 8 — Setting Up and Learning the Language

What You’ll Build

In Chapter 7 you learned why Minecraft is the way it is: a data-driven game whose blocks, items, recipes, and worlds are all described in data files the game reads. So far you’ve made the game do things by typing commands; now you start making those things files. In this chapter you set up the tools to write those files, and you learn the two “languages” every file in this book is written in.

By the end you will have a real workshop: a plain-text code editor installed on your computer, ready for the data pack you build in Chapter 9. (You already have the other half of the workshop: the Creative test world with cheats you’ve been using since Chapter 1.) You’ll also be able to read and write JSON (the format every data-pack file uses) and read identifiers, the namespaced names like minecraft:stone that Minecraft uses to label everything. You won’t build a data pack yet (that’s the next chapter), but you’ll be able to hand-write a valid JSON file, spot the small mistakes that break one, and name your own things the way Minecraft expects.

Concepts

Plain-text editor. A plain-text editor is a program that saves exactly the characters you type and nothing else: no fonts, no bold, no hidden formatting. Data-pack files are plain text, so you need a plain-text editor to write them. Word processors like Microsoft Word or Google Docs are the wrong tool: they add invisible formatting and like to “helpfully” change your straight quotes " into curly quotes ”, which Minecraft cannot read. This is general computer advice, not a Minecraft rule, but it matters: write your files in a code editor, never in a word processor.

Test world. A test world is a throwaway world you use only for trying out data packs: the Creative world with commands allowed that you’ve been using since Chapter 1. The Allow Commands switch is what lets you type commands like /reload, and keeping a separate test world means a broken experiment never touches a world you care about. That’s the world we’ll use here.

JSON. JSON (JavaScript Object Notation) is a lightweight, plain-text way of writing structured data as key-value pairs and lists. Minecraft uses JSON to store many things: the pack.mcmeta file that marks a data pack, and the data-pack files that define advancements, loot tables, tags, recipes, and predicates, among others. If you can read and write JSON, you can read and write data packs.

Identifier. An identifier (also called a resource location or namespaced ID) is a name in the form namespace:path that points to one specific game object (a block, an item, a function, and so on) with no ambiguity. minecraft:stone is the identifier for stone. The namespace is the part before the colon; the path is the part after it.

/reload. The /reload command re-reads the data packs in your world so your latest edits take effect without you leaving and rejoining. It will be the button you press all book long: edit a file, save it, run /reload, see the change. (You’ll learn in Chapter 9 exactly what it reloads.)

Walkthrough

Step 1 — Install a code editor

You need one plain-text code editor. This book recommends Visual Studio Code (usually just called VS Code), a free editor from Microsoft. To get it, open your web browser, search for “Visual Studio Code,” download it from the official site (code.visualstudio.com), and run the installer the normal way for your operating system. If you’d rather use something lighter on Windows, Notepad++ is a fine alternative: same idea, smaller program. Either one works for everything in this book; the listings look the same whichever you pick.

These download-and-install steps are ordinary computer steps, not Minecraft features, so they may look a little different depending on your computer and the year. Follow the official site’s instructions if anything has moved.

Try It! In VS Code you can install extensions (small add-ons). Search its Extensions panel for a JSON or Minecraft data-pack extension and install one. A good one will underline broken JSON in red as you type, which catches the mistakes in the “What Can Go Wrong” section before the game ever sees them. Extensions are optional; everything in this book works without them.

Step 2 — Confirm Your Test World Is Ready

You’ve been using a Creative test world with cheats since Chapter 1, and that’s the one we’ll use, so there’s no new world to make. Just load it and check one thing: that /reload is available, because that’s the command you’ll lean on all book long. Open the chat (press T or /), type the reload command, and press Enter:

/reload

Right now you have no data packs of your own, so nothing visible happens, but the command runs without an error, which tells you commands are allowed and /reload is available. The /reload command re-reads the current data packs; if a pack has invalid data (such as a broken recipe), the game keeps the previous working version instead of applying the broken one. That safety net is why you can edit boldly: a typo won’t corrupt your world, it just won’t load until you fix it.

Modern Minecraft Some data-pack features can’t be refreshed with /reload alone. A handful of “dynamic” things (Minecraft calls them experimental settings, and they include features like custom dimensions and enchantments) only update when you leave the world and rejoin. Most of what you build early on (functions, recipes, loot tables, tags, advancements, predicates) does reload instantly. You met this distinction in Chapter 7; we’ll point it out again when it matters.

Step 3 — Learn JSON by writing a file

JSON is built from a few simple pieces. Make a scratch folder somewhere easy to find (your Desktop is fine) called json-practice, and create a new file in it. Let’s build that file up one piece at a time, then look at the finished version.

Values. A JSON file holds a single value. A value can be one of these basic types:

  • A string: text wrapped in straight double quotes: "hello", "Hello, world". If you need a double quote inside the text, you escape it with a backslash: "An escaped \" quote".
  • A number, written plainly: 2, -0.5. Numbers can have a decimal point and don’t use quotes.
  • A boolean: exactly true or false (no quotes).
  • An object, a labeled box (below).
  • An array, an ordered list (below).

Objects { }. An object is a collection of key-value pairs wrapped in curly brackets. Each pair is a key (a name, in quotes) and a value, joined by a colon; pairs are separated by commas. Every key in one object must be unique. A value can itself be any type, including another object, which is how JSON nests. Here’s the example straight from how Minecraft documents it:

{
  "Bob": {
    "ID": 1234,
    "lastName": "Ramsay"
  },
  "Alice": {
    "ID": 2345,
    "lastName": "Berg"
  }
}

Read it as: an object with two keys, "Bob" and "Alice". Each of their values is another object with an "ID" (a number) and a "lastName" (a string). Objects inside objects: that’s nesting.

Arrays [ ]. An array is an ordered list of values wrapped in square brackets, separated by commas:

["Bob", "Alice", "Carlos", "Eve"]

The values in a JSON array can even be of different types if you want: a number next to a string next to a boolean is allowed.

Now put it together. Here is a complete, valid practice file using every piece: a string, a number, a boolean, a nested object, and an array:

Desktop/json-practice/my_first.json

{
  "name": "My First File",
  "version": 1,
  "finished": false,
  "author": {
    "id": 1234,
    "tools": ["vscode", "minecraft"]
  }
}

Type that in, then save it. If your editor (or its JSON extension) shows no red underlines, the file is valid JSON. Notice the shape: the whole file is one object { }; "author" is a nested object; and "tools" is an array of two strings. Indentation and line breaks are only there to make it readable (JSON doesn’t require them), but they make a long file far easier to follow, so use them.

Under the Hood (skippable) The five value types you’ll use in data packs are string, number, object, array, and boolean; those are the ones worth learning now. Some real data-pack files also use the empty value null to mean “nothing here,” but it’s rare enough that we won’t lean on it yet; you’ll meet null in a later chapter where a real file actually uses it.

Step 4 — Read identifiers and namespaces

Open your test world’s chat and start typing one of the commands you’ve used since Chapter 1, like /give, and the autocomplete shows names like minecraft:diamond and minecraft:stone. Each of those is an identifier: a namespace:path name. In minecraft:stone, the namespace is minecraft and the path is stone.

Why the namespace exists. A namespace is a labeled grouping that keeps two packs’ names from clashing. Imagine two data packs each add a function called start. Without namespaces those two start functions would collide and break. Give them different namespaces, say minigame_one and minigame_two, and they become minigame_one:start and minigame_two:start, which can’t conflict. This is exactly why your data pack will get its own namespace in Chapter 9.

The minecraft: default. Minecraft reserves the minecraft namespace for the vanilla game. In Java Edition, if you write a name with no colon, the game fills in minecraft for you, so stone and minecraft:stone mean the same thing. Because of that, you should only put your files in the minecraft namespace when you specifically want to add to or change vanilla (for example, adding your function to the built-in minecraft:load group, a Chapter 9 topic). For your own content, use your own namespace.

Naming rules (this is a real Minecraft rule, so follow it exactly). In Java Edition, both the namespace and the path may only contain these characters:

  • lowercase letters a–z
  • digits 0–9
  • underscore _
  • hyphen -
  • dot .

The forward slash / is allowed in a path (it makes sub-folders) but not in a namespace. No capital letters, no spaces, no other symbols. The preferred style is snake_case: lowercase words joined by underscores, like my_cool_pack. So mypack:magic_sword is a good identifier; MyPack:Magic Sword is not (capital letters and a space are both illegal).

Pick a good namespace. When you choose your own namespace, make it specific. Don’t use vague “alphabet soup” like nc or an over-broad word like battle_royale; a more descriptive name (your project’s name, or your name plus the project) is easier to find and debug when several packs are loaded at once. In this book the reader’s namespace is always mypack: short, lowercase, and clearly not vanilla.

Modern Minecraft You may see identifiers written without a namespace in old tutorials, like just diamond. That still works in Java Edition because the game assumes minecraft:, but it’s recommended to always write the colon form. Being explicit (minecraft:diamond) makes it obvious which namespace you mean and avoids surprises.

Practice

  1. Write and validate a JSON file. In your json-practice folder, make a new file called pet.json. Inside one object, give it: a "name" string, an "age" number, an "adopted" boolean, and a "favorite_foods" array of two or three strings. Save it. If your editor shows no errors, you wrote valid JSON. (If it does show an error, jump to “What Can Go Wrong.”)

  2. Break it on purpose, then fix it. Add a comma after the last item in your array and save. Watch your editor flag it. Remove the comma to fix it. Getting comfortable making and fixing errors now will pay off in every later chapter.

  3. Spot identifiers in-game. In your test world, press F3 + H together. This turns on “Advanced Tooltips,” so when you hover over any item in your inventory you’ll see its identifier (its namespace:path name) printed under it. Hover over five different items and write down their identifiers. Notice they’re all in the minecraft namespace and all use lowercase snake_case, the same rules you’ll follow for your own names.

Try It! Look closely at the identifiers you collected. Which part is the namespace and which is the path? Can you find an item whose path uses an underscore, like minecraft:iron_ingot? That’s snake_case in the wild.

What Can Go Wrong

A trailing comma. JSON separates items with commas between them, but the last item in an object or array must not be followed by a comma. This is the single most common JSON mistake.

Broken:

{
  "name": "Steve",
  "level": 5,
}

Fixed (the comma after 5 is gone):

{
  "name": "Steve",
  "level": 5
}

A missing or wrong quote. Every key, and every string value, must be wrapped in straight double quotes ". Forgetting one, or letting a word processor turn a straight quote into a curly ”, breaks the file.

Broken:

{ "name": Steve }

Fixed (the string value is now quoted):

{ "name": "Steve" }

A capital letter or space in a name. Identifiers must be lowercase with no spaces. MyPack:Cool Sword is invalid on two counts: the capital letters and the space. Write it as mypack:cool_sword instead. If a data pack later “can’t find” something you named, check first for a stray capital, space, or typo in the identifier.

What You Know Now

You finished setting up your workshop (a plain-text code editor alongside the cheats-on Creative test world you’ve had since Chapter 1) and learned the two languages the rest of the book is written in. You can hand-write a valid JSON file out of objects, arrays, strings, numbers, and booleans; nest one inside another; and spot the trailing-comma, missing-quote, and bad-name mistakes that break a file. You can read an identifier as a namespace:path name, you know minecraft: is the default namespace, and you know the lowercase snake_case naming rules you’ll use for your own mypack content. You can now build your first real data pack: that’s Chapter 9.