How registration works

One shape for every kind of content, the two ways to declare it, and what RetroAPI does with your ids once you hand them over.

Everything in this section, blocks, items, mobs, dimensions, sounds, particles, world features, follows the same three-part shape. Learn it once here and the individual pages are mostly a list of what each builder can do.

The shape

1. Describe it. A builder (RetroBlockAccess.create(...), RetroItemAccess.create(), RetroFeatures.ore(...)) or a plain constructor for your own subclass.
2. Name it. A namespaced identifier: example_mod:ruby_ore. This name is the permanent one, everything else about your content, including its number, is allowed to change.
3. Register it from your retroapi entrypoint (Entrypoints & sides), so it lands at a point where the platform is ready and before any world assigns ids.

// a block
RUBY_ORE = RetroBlockAccess.create(Material.STONE)
    .strength(3.0F).texture(id("ruby_ore")).register(id("ruby_ore"));

// an item
RUBY = RetroItemAccess.create()
    .maxStackSize(64).texture(id("ruby")).register(id("ruby"));

// something that generates in the world
RetroFeatures.ore(RUBY_ORE).size(6).count(8).heightRange(4, 32).register();

Ids move. Names do not.

Beta identifies a block by a number, and a modded block has to be given one. RetroAPI hands out a provisional number at registration and then, when a world is opened, replaces it with whatever that world's saved map says the block should be, so that a world you built last week still has your ore where you left it, even if you have since added or removed content.

IdRemapCallback.EVENT.register(remap -> {
    remap.fix(ExampleMod.STARTER_KIT);                      // an ItemStack field
    ExampleMod.magicId = remap.map(ExampleMod.magicId);      // a raw id
});

Code-driven and data-driven

Most content can be declared as a builder call or as a JSON file under assets/ or data/. Wherever the two are genuine alternatives, a switch sits directly above them and flips the whole wiki between them. They are not alternatives everywhere, though, so here is the honest map:

RUBY_ORE = RetroBlockAccess.create(Material.STONE)
    .register(id("ruby_ore"));   // displays as "Ruby Ore"

tile.example_mod.ruby_ore.name=Ruby Ore

Where the two combine, not compete

The table above has one row that is easy to misread, so it gets its own section. Block states are not an either/or. The two sides do different jobs and a block with visual variants normally needs both.

Declare the property in JSON only and it does exist, but in Java you have to find it by name and cast, which throws away the type safety that made the property object worth having:

@SuppressWarnings("unchecked")
RetroProperty<Boolean> lit =
    (RetroProperty<Boolean>) RetroStates.property(LAMP, "lit");
RetroStates.set(world, x, y, z, state.with(lit, true));

So the usual shape of a lamp that both does something and looks different is: the property in code, the variants in the blockstate file. They agree because they are the same property name; if they disagree, the code declaration wins and the mismatch is logged.

// code: the property you will actually use in game logic
static final RetroBoolProperty LIT = RetroBoolProperty.of("lit");

LAMP = RetroBlockAccess.create(Material.STONE)
    .states(LIT)
    .register(id("lamp"));

{
  // no "properties" needed: the code already declared it
  "variants": {
    "lit=false": { "model": "example_mod:block/lamp_off" },
    "lit=true":  { "model": "example_mod:block/lamp_on" }
  }
}

A block whose states are pure gameplay, a machine that tracks progress but never changes its face, needs no JSON at all. A block that only changes color with its state can stay in code too, using .tint(...) or .overlay(...). It is specifically different models per variant that requires the file.

What each page in this section covers