Modding Beta 1.7.3, the comfortable way

A guided tour from empty folder to custom blocks, machines, mobs, dimensions, and packets.

It's Beta 1.7.3 again, the grass is that particular green, the world is quiet, and there is no modding API. There never was one. What there is, in 2026, is something better: modern tooling pointed backwards. Ornithe gives us a Fabric-style loader and Gradle builds for old versions; biny mappings give the decompiled code human names; OSL provides entrypoints, lifecycle events and networking; and RetroAPI does the dangerous work, block ID expansion, texture atlasing, save-file safety, multiplayer sync, so your mod doesn't have to.

This guide is written as a story in chapters. Each chapter builds one feature of a real, working example mod, with every line of code copyable and every texture downloadable. By the last page you'll have seen a mod with custom blocks, items, a clicking counter, a crate with its own GUI, a fuel-burning freezer with animated progress bars, a mob, an achievement page, a dimension behind a walk-in portal, a welcome packet, and a twelve-step mixin course.

Grab a template

Two zips, one decision:

⬇ bare-retroapi-template.zip , a clean start ⬇ feature-showcase-retroapi-template.zip , everything, built & commented

  • Bare is the official ornithe-mod-template with its build files already converted for b1.7.3 + RetroAPI (the exact conversion is Chapter 1). One example entrypoint, one example mixin, nothing else. Start here.
  • Feature showcase is the mod this guide walks through, every feature finished and heavily commented. Keep it open in a second editor window and steal from it freely (it's CC0).

Already modding modern Minecraft? You'll feel at home: fabric.mod.json, entrypoints, mixins, and Loom all work the way you expect. The differences worth knowing: identifiers come from OSL (NamespacedIdentifiers.from("mod", "thing")), there is no integrated server in b1.7.3 (singleplayer runs entirely client-side, Chapter 2), and the registry is RetroAPI's job, not the game's.

The chapters

Chapter 1The WorkshopSet up Gradle, biny mappings, and fabric.mod.json, then run the game. Chapter 2Three Doors Ininit, client-init, server-init, what runs where, and why textures are safe in common code. Chapter 3Pixels & WordsTexture loading and sprite ids, GUI art, lang files, and the sound autoloader. Chapter 4BlocksOne cube, a multi-sided cube, and a pipe with its own render type. Chapter 5ItemsA simple item, then the Jump Stick, custom classes and right-click behavior. Chapter 6MachinesBlock entities: a click counter, a crate with a GUI, and the freezer, with synced progress bars. Chapter 7CreaturesA custom mob, its renderer, and the truth about entity networking. Chapter 8The AerbunnyA complex mob in full: riding, slow-fall gliding, breeding, fear AI, and the input/mount networking behind them. Chapter 9AchievementsToasts, parent trees, your own page, and granting from gameplay. Chapter 10Other WorldsRegister a dimension and walk into it through a portal block. Chapter 11RecipesShaped, shapeless, smelting, fuel, and metadata wildcards. Chapter 12WiresCustom packets with OSL: a welcome message and its reply. Chapter 13The ScalpelWhy beta modding is mixin-heavy, how to cut safely, and 12 graded examples. Chapter 14Deeper StatesFlattened blockstates: properties, secondary meta, and a 20-state lamp. Chapter 15True ShapesVoxelShapes: multi-box outlines, collision, and mining through the gaps. Chapter 16Shapes & PixelsJSON block and item models, render layers, tints, and animated textures. Chapter 17Facing the WorldDirectional blocks: a log whose grain flips, a freezer that faces the placer. Chapter 18The ToolbeltCustom tools, the food API with a poisonous apple, and a full zanite armor set. Chapter 19The SoundtrackSound effects, streaming music, shuffled background tracks, and jukebox records. Chapter 20New LandsChunk generators, Perlin terrain, biomes, spawn rules, and dimension portals. Chapter 21Item MemoryData components: typed item data, tooltips, and component-driven textures. Chapter 22Proving GroundsrunClient, runServer, offline mode, and the sided-code checklist.

The two-minute version

For the impatient, this is most of the API:

the elevator pitch
// blocks (Chapter 4)
Block myBlock = RetroBlockAccess.create(Material.STONE)
    .strength(1.5f, 10.0f).texture(id("my_block")).register(id("my_block"));

// items (Chapter 5)
Item myItem = RetroItemAccess.create()
    .maxStackSize(64).texture(id("my_item")).register(id("my_item"));

// recipes (Chapter 11)
RetroRecipes.addShaped(new ItemStack(myBlock), "CC", "CC", 'C', Block.COBBLESTONE);

// achievements (Chapter 9)
Achievement first = RetroAchievements.register(id("first"), "my_mod.first", 0, 0, myItem, null);

// dimensions (Chapter 10)
DimensionRegistration dim = RetroDimensions.register(id("my_dim"), MyDimension::new);

// entities (Chapter 7)
RetroEntities.register(MyMob.ID, MyMob.class).factory((MobFactory) MyMob::new);

Everything persists across world saves, survives being opened in vanilla, and syncs over multiplayer, that's the part RetroAPI quietly handles for you.

Ready? Chapter 1: The Workshop →