---
type: Log
title: Spigot Inventory Helper Design Log
description: Chronological record of material decisions affecting the Spigot Inventory Helper design.
---

# Spigot Inventory Helper Design Log

## 2026-09-04 — Initial inventory-helper design

- Players will be able to craft a metadata-authenticated Sorting Stick.
- The Sorting Stick will sort chests, double chests, barrels, or the player's main storage inventory depending on the interaction target.
- Player-inventory sorting will leave the hotbar, armor, and off-hand slots unchanged.
- When a main-hand tool breaks, an equivalent tool with the same material and tool type will be moved from the player's inventory into the selected hotbar slot when available.
- The knowledge bundle and eventual Gradle, Purpur, Gitea CI, and semantic-release setup will follow the neighboring Spigot Base project where applicable.

## 2026-09-04 — Sorting Stick recipe

- The Sorting Stick uses a vertical recipe in the crafting grid's center column: a Chest or Barrel above Redstone Dust, with a Stick at the bottom.
- Either storage-block variant produces one Sorting Stick.

## 2026-09-04 — Build and release foundation completed

- Added the Java 25 Gradle build, Purpur API dependency, strict compiler linting, JUnit 5 lifecycle, plugin metadata, and initial plugin entry point.
- Added Gitea CI, conventional-commit validation for pull requests, development artifacts, semantic releases, and release-asset upload.
- Verified `./gradlew clean check jar`, successful main and tag CI runs, and release `v1.0.0` with `spigot-inventory-helper-1.0.0.jar` attached.

## 2026-09-04 — Sorting Stick completed

- Added a gold-named, glinting Sorting Stick authenticated by persistent item metadata.
- Registered equivalent chest and barrel recipe variants matching the approved center-column shape.
- Verified recipe specification, registration, output, item appearance, identity, and renamed-stick rejection with automated tests and `./gradlew clean check jar`.

## 2026-09-04 — Inventory sorting completed

- Added metadata-preserving stack consolidation and stable alphabetical ordering by Minecraft material.
- Added Sorting Stick interactions for single and double chests, barrels, and player main-storage slots while preserving hotbar, armor, and off-hand slots.
- Rejected locked containers, cancelled protection events, non-right-click interactions, and unauthenticated sticks without changing inventories.
- Added action-bar feedback, documented player behavior, and verified the complete feature with `./gradlew clean check jar`.

## 2026-09-04 — Automatic tool replacement completed

- Added next-tick replacement of broken main-hand tools with exact-material matches from player storage.
- Main storage is searched before other hotbar slots, and the replacement item is moved intact into the captured selected slot without overwriting a newly occupied slot.
- Off-hand breaks and unavailable or mismatched replacements leave inventory unchanged.
- Added player feedback and verified matching, source priority, metadata-preserving movement, safety, and off-hand behavior with automated tests and `./gradlew clean check jar`.

## 2026-09-04 — Implementation started

- Approved implementation begins with the tested Gradle and Purpur foundation, followed by the Sorting Stick, inventory sorting, and automatic tool replacement.
- Work proceeds one user story at a time using red-green-refactor cycles and a verified commit and push after each completed story.