Scripting guide

Introduction

Scripts run entirely in your browser, inside an isolated JavaScript interpreter. Nothing is uploaded while you experiment: you write code on one side of the editor, press Run, and the blocks it places appear in the 2D and 3D viewers on the other side.

The point of a script, rather than a one-off build, is that other people can run it with different settings. A script that declares inputs gets a panel of controls beside the viewer, so someone who has never read your code can change the size, the material, or the seed and export the result.

Your first script

Open the editor, replace what is there with the following, and press Run. It lays an 8 by 8 stone floor and puts a torch in the middle of it.

function main(context) {
  const { Creation } = context;

  const creation = Creation('My first build');

  creation.fillBox(0, 0, 0, 7, 0, 7, 'minecraft:stone');
  creation.setBlock(3, 1, 3, 'minecraft:torch');

  return { creation };
}

Three things are worth noticing. Coordinates are integers, and y is the vertical axis, so the torch sits one block above the floor. fillBox takes two opposite corners and fills everything between them, which is far faster than looping. And every script hands its work back by returning { creation }; a script that builds a creation but never returns it produces nothing.

Block ids are the vanilla ones, with the minecraft: namespace. The editor autocompletes them as soon as you start typing inside a string, so you rarely have to look one up.

Anatomy of a script

A script is plain JavaScript with two special top-level functions. You may use TypeScript syntax if you prefer: types are stripped before the script is stored or run.

main(context, inputs)

Required. This is what runs when someone presses Run. It receives the context object holding every helper, and the current values of the inputs you declared. It must return an object containing a creation, and may also return a camera.

defineInputs(context)

Optional. Return a map of input definitions and the editor renders a control for each one. The values then arrive as the second argument to main, keyed the same way.

function defineInputs(context) {
  const { Input } = context;

  return {
    size: Input.number({
      label: 'Size',
      description: 'Length of each side, in blocks',
      defaultValue: 8,
      min: 1,
      max: 64,
    }),
    material: Input.block({
      label: 'Material',
      defaultValue: 'minecraft:stone',
    }),
  };
}

function main(context, inputs) {
  const { Creation } = context;

  const creation = Creation('Platform');
  const last = inputs.size - 1;

  creation.fillBox(0, 0, 0, last, 0, last, inputs.material);

  return { creation };
}

Placing blocks

A creation collects block operations in the order you make them. Later writes to the same cell win, so you can lay a solid shape and then carve into it.

You do not need to build at the origin. The build is normalised to its own bounding box on export, so negative coordinates and whatever offsets are convenient for your maths are fine.

For anything large, prefer fillBox over nested loops: one operation covering a million blocks is cheaper to produce, store and render than a million operations. Loop only where the shape genuinely varies per block.

Block states

Stairs face a direction, logs have an axis, doors have a half. These are block states, and they are always passed as strings, including "true" and "false".

// States are always strings, including "true" and "false".
creation.setBlock(0, 0, 0, 'minecraft:oak_stairs', {
  facing: 'east',
  half: 'bottom',
  shape: 'straight',
  waterlogged: 'false',
});

// Ask rather than guess: a bare banner has no placeable default.
const states = Textures.getPlacementStates('minecraft:white_banner');
creation.setBlock(2, 0, 0, 'minecraft:white_banner', states);

// Two-cell blocks place their other half for you, in the right
// direction: this one call leaves a whole bed facing east, so the
// head lands in the cell at x=5.
creation.setBlock(4, 0, 0, 'minecraft:red_bed', { facing: 'east' });

A block's own defaults are often not placeable ones, which is the most common reason a single-cell block looks wrong in the viewer. Textures.getPlacementStates returns the states that let a block stand on the ground, and Textures.getStateOptions lists every state a block accepts along with its legal values. Use them instead of guessing from the block name.

Inputs

Each helper on Input produces one control. The type of the value that reaches main follows from the helper you used.

Options every input accepts

folder and order are worth using as soon as a script has more than a handful of controls, and visibleWhen keeps a panel honest when a script branches: an input that only matters in one mode should not be visible in the other.

Files and images

Scripts cannot reach the network, so anything from outside comes in through a file input. A file arrives as a ScriptFile: name, type, size, plus text for text files, dataUrl, and imageData for images.

imageData is { width, height, data }, where data is flat RGBA, four entries per pixel, rows running top to bottom. Since Y runs upwards in a build, you will usually flip the row index.

function defineInputs(context) {
  const { Input } = context;

  return {
    image: Input.file({
      label: 'Image',
      accept: 'image/*',
      paintable: true,
    }),
  };
}

function main(context, inputs) {
  const { Creation, Textures } = context;

  const creation = Creation('Pixel art');
  const image = inputs.image;
  if (!image || !image.imageData) return { creation };

  const { width, height, data } = image.imageData;

  for (let y = 0; y < height; y++) {
    for (let x = 0; x < width; x++) {
      const at = (y * width + x) * 4;
      if (data[at + 3] < 128) continue; // Skip transparent pixels.

      const block = Textures.findClosestBlockToColor(
        data[at],
        data[at + 1],
        data[at + 2],
      );
      // Image rows run top-down, Y runs up, so flip the row.
      creation.setBlock(x, height - 1 - y, 0, block);
    }
  }

  return { creation };
}

Setting paintable: true on an image input gives the viewer an in-app painter instead of a file picker, which is a good default for scripts where the image is a sketch rather than a photo.

A file input holding a structure file is special: the host parses it for you before main starts, and Structures.getLoadedSchem() hands back the blocks it contains. With no name it resolves the input called schematic; pass an input name to pick one when a script takes several builds, as a diff does.

function defineInputs(context) {
  const { Input } = context;

  // The host pre-parses a file input named exactly `schematic`.
  return {
    schematic: Input.file({ label: 'Build', accept: '.litematic,.schem,.nbt' }),
  };
}

function main(context) {
  const { Creation, Structures, Logger } = context;

  const creation = Creation('Doubled');
  const loaded = Structures.getLoadedSchem();

  if (!loaded.ok) {
    Logger.warn(loaded.error);
    return { creation };
  }

  for (const op of loaded.operations) {
    creation.setBlock(op.x * 2, op.y, op.z * 2, op.name, op.states);
  }

  return { creation };
}

Framing the result

Return a camera next to the creation to choose where the 3D viewer starts. Useful when the interesting side of a build is not the one the default camera lands on.

return {
  creation,
  camera: {
    position: [40, 30, 40],
    target: [0, 8, 0],
  },
};

Marking blocks

Return highlights to have the 3D viewer draw a coloured border around named cells. The blocks keep their own models, so this says something about a cell without repainting the build: which blocks a diff added, which cells a check flagged, which ones a pass touched.

Each entry is a { color, blocks } pair, where color is a hex string such as #22c55e and blocks is a list of [x, y, z] cells. Up to eight groups and 200,000 outlined cells are drawn per run, and an entry the viewer cannot read is skipped rather than failing the script.

function main(context) {
  const { Creation } = context;

  const creation = Creation('Review');
  const added = [];

  creation.setBlock(0, 0, 0, 'minecraft:stone');
  added.push([0, 0, 0]);

  // Each block still renders as itself; only the border is coloured.
  return {
    creation,
    highlights: [{ color: '#22c55e', blocks: added }],
  };
}

Reference: context

Both defineInputs and main receive a context object. Destructure what you need from it rather than reaching for globals.

function main(context, inputs) {
  const { Creation, Logger, Textures, Structures } = context;
  // ...
}

Reference: Creation

creation.setBlock(0, 0, 0, 'minecraft:oak_log', { axis: 'y' });

creation.fillBox(0, 0, 0, 15, 0, 15, {
  name: 'minecraft:oak_log',
  states: { axis: 'x' },
});

Reference: Input

Available on the context passed to defineInputs. See Inputs above for the full option tables.

sourceEntity: Input.select({
  label: 'Entity',
  options: Textures.listMobModels().map((model) => model.id),
  visibleWhen: { input: 'sourceType', in: ['entity'] },
})

Reference: Logger

Logger.info('placed', creation.getOperations().length, 'operations');

Reference: Textures

The largest namespace, and the one that turns a script from a shape generator into something that knows about Minecraft. Only the listing calls work inside defineInputs.

Listing blocks

Colour matching

const block = Textures.findClosestBlockToColor(200, 60, 40, palette, {
  colorSource: 'dominant',
  metric: 'ciede2000',
});

States and shapes

Models and textures

Mobs and skins

Reference: Structures

const chunkIds = await Structures.generate({
  structureId: 'minecraft:village/plains/town_centers',
  depth: 7,
});

Reference: Generators

Four namespaces produce ready-made shapes. All of them return setBlock operations anchored at the origin rather than drawing anything, so you can offset, filter or repeat their output before it reaches the creation.

function main(context) {
  const { Creation, Trees, Rocks } = context;

  const creation = Creation('Grove');

  // Generators return operations rather than drawing anything themselves,
  // so you can filter or offset them before they reach the creation.
  creation.addOperations(Trees.generate({ species: 'Oak', seed: 1, count: 3, spread: 12 }));
  creation.addOperations(Rocks.generate({ formation: 'Boulder', seed: 7, size: 5 }));

  return { creation };
}

Sandbox and limits

Scripts run in an isolated QuickJS interpreter. There is no DOM, no window, no document, no timers and no network access. A script that needs outside data takes a file input.

While a script runs

Troubleshooting

No main function defined

The script parsed but never declared main. Declare it as a top-level function, not nested inside another one and not assigned conditionally.

Invalid script block name

A setBlock or fillBox call received something that is not a block id string. This usually comes from a lookup that can miss, such as a palette index that ran past the end of an array.

Invalid script coordinate

A coordinate was NaN, infinite, or outside ±30,000,000. Almost always a division by zero or an input parsed into NaN.

The script runs but nothing appears

Check that main returns { creation }, and that the creation you return is the one you placed blocks into.

A block renders as a plain cube or a bare post

It was placed without usable states. Use Textures.getPlacementStates, and Textures.getStateOptions for the connections on panes, fences and walls.