Beadmatica

Beadmatica

A client-side blueprint companion mod for Brainlayers. It lets you import a bead artwork from a JSON file, mount it onto a pegboard table, and see at a glance which beads you are still missing — all without touching the artwork's actual block data.

---

Background

Brainlayers' pegboard tables have no notion of a "target pattern". You either place beads by hand or eyeball it against a reference image. There is also no way to ask "how many red beads does this 128×128 piece need, and how many do I actually have in my shulker boxes?"

Beadmatica adds both: a server-authoritative blueprint attachment for pegboard tables, and a client-side overlay that renders the blueprint on top of the table and diffs it against your inventory.

---

What This Does

• Imports blueprints from JSON — a client-side scanner reads beadBluePrint/*.json and parses the same pixel convention Brainlayers uses (0 = empty, otherwise palette index + 1).
• Mounts a blueprint onto a table — the blueprint is stored in the block entity's persistent data and survives chunk and world reloads via a BlockEntity mixin.
• Server-authoritative loading — load, unload, refresh, and query all go through a registered network channel, so a blueprint cannot be forged or mounted remotely.
• Renders an in-world overlay — a PegboardTableRenderer tail injection appends the blueprint layer after Brainlayers' own drawing, so the vanilla board is never replaced.
• Renders an in-screen overlay and side panel — an AbstractContainerScreen tail injection adds the blueprint overlay, a blueprint selection panel, and a colour list to the pegboard screen.
• Diffs against your inventory — ShulkerCounter counts beads held directly and inside any shulker box you are carrying, then reports only the colours you are short on.
• Exports a material list — MaterialExporter writes a plain-text missing-bead list through the platform file dialog.
• Live refresh — while a pegboard screen is open, the client rescans the blueprint folder on a configurable interval and pushes changes to the server.

---

Blueprint Format

A blueprint is a JSON file placed in .minecraft/beadBluePrint/. The file name (minus extension) becomes the blueprint name.

{
  "boardSize": 16,
  "pixels": [0, 0, 1, 0, ...]
}

• boardSize must be one of 16, 32, 64, 128.
• pixels must contain exactly boardSize * boardSize entries.
• Each entry is 0 for an empty cell, otherwise a palette index + 1.
• Out-of-range colours are sanitized to empty cells rather than rejected.
• Unknown extra fields and version values are tolerated.

---

Persistence

BlueprintHolder bridges blueprint data into BlockEntity.getPersistentData(). Because that tag is a Forge addition and is not written by saveAdditional() by default, a BlockEntityMixin copies it into the block entity's own NBT on save and reads it back on load.

Two extra safety behaviours:

• setRemoved clears the blueprint from persistent data when the block entity is removed, so a stale blueprint cannot linger.
• The loader UUID is stored alongside the blueprint, so ownership can be checked on unload.

---

Network Protocol

All packets are registered on a single SimpleChannel with protocol version "1".

Direction	Packet	Purpose
Serverbound	ServerboundBlueprintLoad	Mount a blueprint onto a table. Rejected if already loaded by another player.
Serverbound	ServerboundBlueprintUnload	Remove a blueprint. Only the original loader may do this.
Serverbound	ServerboundBlueprintRefresh	Update an already-loaded blueprint (file changed) or drop it (file deleted).
Serverbound	ServerboundBlueprintQuery	Ask the server for the current blueprint at a position.
Clientbound	ClientboundBlueprintSync	Push the loaded/unloaded state of a table to clients.

Every serverbound handler validates:

• the sender is non-null;
• the target position is within 64 blocks of the player;
• the block entity is actually a PegboardTableBlockEntity;
• the declared board size matches the table's canvas size.

Ownership is enforced on unload: only the UUID that loaded a blueprint may remove it. On load, an existing blueprint may be replaced only by its original loader; anyone else is told to unload first.

---

Rendering Hooks

Mixin	Target	What it does
PegboardTableRendererMixin	PegboardTableRenderer.render	Appends the blueprint overlay at TAIL.
AbstractContainerScreenMixin	AbstractContainerScreen.render	Renders the overlay, the blueprint panel, and the colour list when the screen is a PegboardScreen.
AbstractContainerScreenMixin	AbstractContainerScreen.mouseClicked	Routes clicks to the blueprint panel first.
BlockEntityMixin	BlockEntity.saveAdditional / load / setRemoved	Persists and clears the blueprint NBT.

PegboardTableRenderer is final, so the mod does not attempt to replace the registered renderer — that would lose Brainlayers' own drawing. Appending at TAIL keeps both layers intact.

---

Configuration

Common (beadmatica-common.toml)

• scanInterval — how often (in ticks) the client rescans the blueprint folder while a pegboard screen is open. 20 = 1 second. 0 disables automatic rescanning.

Client (beadmatica-client.toml)

• hudDefault — whether the missing-material HUD is enabled by default.
• exportDir — default directory for exported material lists. Leave empty to always prompt with a file dialog.

---

Controls

Key	Action
B	Open the blueprint screen.

The key mapping is registered under the beadmatica.category category.

---

Requirements

• Minecraft Forge
• Brainlayers
• Log prefix: [Beadmatica] (via LogUtils)