blockcompanion

BlockCompanion

BlockCompanion shows a schematic in your world as ghost blocks so you can build it. It covers what Litematica does for placing and checking a build, with less on screen and simpler controls.

It is also the in-game companion to BlockDesigner, a Windows editor for Minecraft builds. It reads the projects and schematics BlockDesigner saves, saves builds from the world back as .schem files BlockDesigner opens, and with BlockDesigner's BlockCompanion Plugin the game and the app link up live.

BlockCompanion is in early development. Bug reports and ideas are welcome on the issue tracker.

Requirements

Mod Menu is optional on Fabric and opens the settings screen from the mod list.

The mod is for the client. Putting it on a Fabric or NeoForge server as well (or the separate BlockCompanion Paper plugin on Paper 1.21.1 servers) adds shared schematics, AutoBuild and fetching blocks from linked chests on that server. Without it, the mod still works on vanilla servers, including easy place in survival.

Getting started

1. Install the jar for your loader and Minecraft version (plus Fabric API on Fabric).
2. Start the game once. It makes <game folder>/blockcompanion/schematics.
3. Put your BlockDesigner projects (.bdproj) and schematics (.schem, .litematic, .nbt) in that folder. The schematic screen has an Open folder button.
4. Press B, pick a schematic and click Load. It appears just in front of you.
5. Hold a stick and look at the schematic's box to move, turn and mirror it (see Controls below), then start building.

New to it? The title screen's BlockCompanion tutorial button opens a world made for learning: each step asks you to do one thing, tells you when you've got it, and takes you to the next. Chapter 1 covers the basics, chapter 2 your own schematics, chests, AutoBuild, sharing on a server and the live link to BlockDesigner.

A short guide also opens the first time you are in a world; the Guide button in the settings and in the BlockCompanion menu opens it again.

Features

Schematics

• BlockDesigner's formats first: BlockDesigner projects (.bdproj) and Sponge schematics (.schem, v2 and v3). Litematica (.litematic) and vanilla structure (.nbt) files load too.
• Whole projects: a .bdproj loads as one schematic with its visible layers merged, each with its own offset, rotation and mirror as in BlockDesigner.
• The schematic screen (B) in four steps:
  • Source: your schematic folder (or a BlockCompanion server's shared schematics), with Load, Unload and Delete.
  • Placement: what is loaded, where, how far it is built, locks, show / hide, bring here, turn, mirror and Live.
  • Resources: what the build still needs, and AutoBuild.
  • BlockDesigner: the live link's status, Start / Stop, Get project and Send now.
• Several schematics at once, each saved per world and server with its position, turn, layer and locks.
• Locking: Position, In place (position, turning and mirroring) or Everything (the layer view too). A locked box has a blue outline.
• Save from the world: mark two corners with the stick, press O, name it, and it is saved as a Sponge v3 .schem with chest contents, signs and entities, ready to open in BlockDesigner.

A clean view

• Only what differs from the world is drawn: ghosts where a block is missing, red over a wrong block (or one facing the wrong way), orange where something is in the way. Grass, flowers, water and snow don't count as in the way.
• Ghosts use the game's own block models and your resource packs, lit by the world, slightly tinted and pulsing. Chests, signs, beds, banners, heads, shulker boxes, bells and lecterns show their real shapes; water and lava their real surface.
• The real block replaces its ghost the moment it is placed, by you or anyone else.
• Schematic boxes only show while the stick is in your hand (or always, if you prefer).
• Touching red or orange blocks share one outline and one tint, so a schematic loaded into a hillside or over an old build stays smooth.
• Built per 16x16x16 section and rebuilt only where something changed, so it stays light on the game.

Building

• Easy place (on by default, H): right-click a ghost with its block to place exactly that block there, turned the right way, even in mid-air. It takes the block from your inventory if it isn't in your hand, and works in survival on vanilla and Paper servers.
• Auto place (off by default, on a key you choose): the missing blocks within reach place themselves from what you carry, bottom layer first and nearest first. 4 blocks a second by default, up to 20. A BlockCompanion server can cap it or switch it off.
• AutoBuild: when your linked chests hold everything a placement still needs, Start AutoBuild on the Resources step has the server build it for you, like Create's Schematicannon, taking each item out of your chests. Its Options set the speed (1 to 200 blocks a second), the order (bottom up, top down, nearest first or one block type at a time), what it may replace (nothing, solid blocks, everything, or also clearing where the schematic has air), a radius around you, and whether to build only the blocks matching the item in your hand. It pauses when an item runs out (or skips those blocks), shows its progress on the action bar, and in creative needs no chests. It needs BlockCompanion on the server (always there in singleplayer); server owners can switch it off, choose who may use it, and cap its speed, radius and what it may break.
• Pick block (middle click) on a ghost selects its item.
• Info panel (bottom left): the schematic, a progress bar, the current layer, the block in your hand with how many are left and how many your chests hold, and what is locked.
• Tool panel (bottom right, while holding the stick): the tool's mode and its controls.
• Crosshair hint: what a wrong block should be, or which block a ghost is.
• HUD editor: drag and resize the info panel, hint and tool panel, or switch any of them off.
• Material helper: holding a block marks the nearest ghosts that need it.
• Small celebrations: sparkles for correct blocks, a toast when a layer is done, fireworks and a summary (time, blocks, accuracy) when the build is finished. Each can be switched off.

Layers

• PgUp / PgDn step through the levels of a schematic, like BlockDesigner's slice view. Levels build up by default; Insert switches to one level at a time. Finishing a level steps to the next.
• V cycles the view: everything, layers up to here, this layer only, only this schematic, hidden.

Undo and redo

• Ctrl+Z undoes and Ctrl+Y or Ctrl+Shift+Z redoes, with one history across every loaded schematic and the selection: moves, turns, mirroring, locks, layers and views. No stick needed, and undo never moves a locked schematic.

Resources and linked chests

• N opens the resource list: how many of each item the build needs, how many are placed, carried, in your linked chests, and still to get, each with a bar that fills from red to green. It updates by itself.
• Linked chests: hold the stick and Ctrl+right-click a chest, barrel or shulker box to link it. Its contents count as materials in the resource list, the info panel and BlockDesigner's BlockCompanion Plugin. A chest is read when you link it and each time you close it.
• On a BlockCompanion server (and in singleplayer), easy place fetches blocks from your linked chests when you don't carry them.

Live link to BlockDesigner

With BlockDesigner open and its BlockCompanion Plugin (1.2.0 or later) on, the game and the app find each other on the same computer.

• Send to game: the project open in BlockDesigner appears in front of you in the game.
• Live: every change you make in BlockDesigner reaches the game a moment later, and the ghosts follow.
• Grab from BlockDesigner: ask the app for the project it has open.
• Edit in BlockDesigner: open a placed schematic in BlockDesigner; the placement then follows your edits where it stands.
• Back to the app: what is loaded, how far each build is and what your linked chests hold show in BlockCompanion Plugin.
• Install mod… in BlockCompanion Plugin puts the latest BlockCompanion into a game's mods folder.

Servers

• One shared place per server to upload, share and lock schematics and BlockDesigner projects, on Fabric and NeoForge servers with the mod, or on Paper with the plugin.
• Server owners can switch off easy place, auto place and AutoBuild, limit who may use AutoBuild, and cap its speed, radius and what it may break.

Settings and updates

• A settings screen (from its key, the schematic screen, Mod Menu or NeoForge's mod list) with sections for Ghosts, Building, HUD, Effects, Colours, Keys and BlockDesigner. Changes apply at once and are saved; each section can be reset.
• Every colour can be changed, with presets including a colour-blind safe one.
• Every key can be rebound on the Keys tab, and the stick's modifier keys on the Building tab.
• BlockCompanion never downloads anything by itself and never sends data over the internet. Update it here on this page.

Privacy and files

• The live link to BlockDesigner only listens on your own computer (127.0.0.1) and accepts a connection only with a random token. Nothing is sent to any server on the internet, and there is no analytics or tracking.

- Files it writes outside the game folder: small status files in ~/.blockcompanion/instances (so BlockDesigner can find a running game) and build progress in ~/.blockcompanion/progress. Your schematics stay in <game folder>/blockcompanion/schematics.

Controls

All keys can be rebound in Options > Controls > BlockCompanion or on the settings screen's Keys tab.

With the stick in hand, looking at a schematic's box:

Plain scrolling always changes the hotbar as usual, and the stick never breaks or uses the block you click.

BlockCompanion is open source under the MIT license.