# 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](https://github.com/doolecg/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](https://github.com/doolecg/BlockCompanion/issues). *** ## Requirements | Loader |Minecraft |Java |Also needs | | -------- |--------- |---- |------------ | | Fabric |1.21.1 |21 |Fabric API | | Fabric |26.2 |25 |Fabric API | | Fabric |26.3 |25 |Fabric API | | NeoForge |1.21.1 |21 |nothing else | | NeoForge |26.2 |25 |nothing else | | NeoForge |26.3 |25 |nothing else | [Mod Menu](https://www.curseforge.com/minecraft/mc-mods/modmenu) 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 `/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 `/blockcompanion/schematics`. ## Controls All keys can be rebound in **Options > Controls > BlockCompanion** or on the settings screen's Keys tab. | Key |Action | | ----------------------- |-------------------------------------------------------------------------------------------------------------------------------------- | | B |Schematic screen | | N |Resource list | | V |Cycle the view of the schematic you look at | | PgUp / PgDn |Layer up / down | | Insert |One layer / build up | | M |Mirror (stick in hand) | | Y |Lock / unlock the schematic you look at | | H |Easy place on / off | | K |Mark a selection corner | | O |Save the selection as .schem | | Ctrl+Z |Undo | | Ctrl+Y or Ctrl+Shift+Z |Redo | | Middle click on a ghost |Pick its block | | (unbound) |Auto place on / off, settings, grab from BlockDesigner, next schematic | | (unbound) |HUD on / off, ghost shimmer on / off, block entity ghosts on / off, boxes always shown or only with the tool, material helper on / off | With the **stick** in hand, looking at a schematic's box: | Input |Action | | -------------------------------- |--------------------------------------------------------------------- | | Shift+scroll |Move one block along the face you look at (or mirror, in Mirror mode) | | Ctrl+scroll |Turn 90 degrees | | Ctrl+Shift+scroll |Switch between Move and Mirror mode | | Alt+left-click / Alt+right-click |Selection corner 1 / 2 | | Shift+right-click |Clear the selection | | Ctrl+right-click a chest |Link / unlink it | 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.

blockcompanion

0.4.5