todo.lock

[AI INSTRUCTIONS]
This is the TODO tracker for this project. The content below shows the current tasks and their statuses.
Prefer fixing bugs before moving on to new features.
Tasks prefixed with [MAJOR] or [DANGER] should only be touched after explicit approval.
Tasks prefixed with [LOW PRIO] or similar can be deferred if necessary.
Tasks marked as [DONE] have been completed and should not be suggested for new work.
[END AI INSTRUCTIONS]


[DONE — Phase 1: Foundation]
- [DONE] Build system: build.gradle, settings.gradle, gradle.properties, neoforge.mods.toml, pack.mcmeta
- [DONE] ResearchTier enum (7 values: IRRECOVERABLE → SELF_AWARE), StringRepresentable
- [DONE] DriveItem — tiered, CustomData recipe storage, foil effect, tooltip
- [DONE] CubeItem — tiered, tooltip
- [DONE] ModItems — 7 Drives (metadata_*), 6 Cubes, research_station_item
- [DONE] ModBlocks — ResearchTableBlock
- [DONE] ModBlockEntities — RESEARCH_STATION type
- [DONE] ModCreativeTabs — ResearchCube tab with all items
- [DONE] NbtUtil — CustomData helpers for tier/recipe read/write
- [DONE] TierUtil — canResearch() validation
- [DONE] Item model JSONs for all cube_* items and research_station_item
- [DONE] Item textures (PNG) generated for all cube_* items and research_station_item

[DONE — Phase 2: Research System]
- [DONE] Prerequisite interface + AndPrerequisite, OrPrerequisite, SinglePrerequisite, NonePrerequisite
- [DONE] PrerequisiteParser — recursive JSON → Prerequisite tree (string, AND/OR objects)
- [DONE] ResearchDefinition record (id, tier, duration, prerequisites, itemCosts, recipePool)
- [DONE] ItemCost record (itemId, count, getItem())
- [DONE] ResearchRegistry — static Map with get/getAll/getByTier/getUpToTier
- [DONE] ResearchManager — SimpleJsonResourceReloadListener scanning data/{ns}/research/*.json
- [DONE] ModServerEvents — AddReloadListenerEvent registration
- [DONE] ResearchTableBlockEntity — 8 slots, tryStartResearch(), serverTick(), completeResearch(), getProgress(), NBT persistence
- [DONE] Example research datapacks: basic_circuit.json, energy_handling.json, advanced_processor.json

[DONE — Phase 3: Custom Recipe System]
- [DONE] DriveCraftingRecipe — CraftingRecipe checking drive NBT + shapeless ingredients, drive consumed
- [DONE] DriveCraftingRecipeSerializer — MapCodec + StreamCodec
- [DONE] ModRecipeTypes, ModRecipeSerializers registered in ResearchCubeMod
- [DONE] Example recipe JSONs: basic_circuit_recipe_1, energy_handling_recipe_1, processor_recipe_1, processor_recipe_2

[DONE — Phase 4: Menu, Screen, Networking, GeckoLib]
- [DONE] ResearchTableMenu — 8 BE slots + player inventory, ContainerData syncing progress (×1000) and isResearching flag
- [DONE] ModMenus — RESEARCH_TABLE MenuType via IMenuTypeExtension
- [DONE] ResearchTableScreen — scrollable research list (filtered by cube tier), row selection, Start button, green progress bar with % text, mouseScrolled support
- [DONE] GUI texture: assets/researchcube/textures/gui/research_table.png (256×256)
- [DONE] StartResearchPacket — client→server, BlockPos + researchId, StreamCodec
- [DONE] ModNetworking — RegisterPayloadHandlersEvent, playToServer registration
- [DONE] ResearchTableBlock.useWithoutItem() — opens menu via ServerPlayer.openMenu with pos buffer
- [DONE] ResearchTableBlockEntity implements GeoBlockEntity — AnimatableInstanceCache, idle animation controller
- [DONE] ResearchStationModel — geo/texture/animation ResourceLocations
- [DONE] ResearchStationRenderer — GeoBlockRenderer subclass
- [DONE] ModClientEvents — registers screen + block entity renderer (Dist.CLIENT, MOD bus)


[TODO LIST]

Current Bugs
- (none confirmed — build is green and client runs cleanly)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Resolved Decision Backlog (implement before Phase 10/11)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

- [DONE] Drive recipe stripping (reverted): DriveCraftingRecipe.getRemainingItems() and DriveCraftingTableMenu.onResultTaken() were updated to return the drive unchanged — the recipe_id is kept forever so the same recipe can be crafted any number of times. NbtUtil.removeRecipe() remains in the codebase for potential future use.

- [DONE] Per-team research sharing: refactored ResearchSavedData from UUID-keyed (Map<UUID, Set<ResourceLocation>>) to String-keyed map. Key = \"team:<teamname>\" for players in a scoreboard team, otherwise UUID string. Added static getResearchKey(ServerPlayer) helper. Updated all call-sites: ResearchTableBlock, StartResearchPacket, ResearchTableBlockEntity (stores researchKey instead of UUID, with backwards-compat loading of legacy ResearcherUUID NBT), and ResearchBookItem.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
DONE — Phase 5: Core Gameplay Gaps]
- [DONE] Per-player completed research tracking — ResearchSavedData (SavedData) stores Map<UUID, Set<ResourceLocation>>. StartResearchPacket & completeResearch() wired. Prerequisite enforcement works.
- [DONE] CancelResearchPacket — client→server packet, cancelResearchWithRefund() refunds consumedCosts into cost slots, Cancel button in screen active while isResearching.
- [DONE] Research name/description in JSON — optional "name" + "description" fields in ResearchDefinition; ResearchManager parses them; screen uses getDisplayName(); all example JSONs updated.
- [DONE] Drive capacity per tier — ResearchTier.maxRecipes (0/2/4/8/12/16/-1), DriveItem.isFull(), tooltip shows X/max, completeResearch() double-checks capacity.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[DONE — Phase 6: UI Polish]
- [DONE] Research row tooltip — hover shows tier, duration, item costs, prerequisite IDs with green ✔/red ✘ status.
- [DONE] Lock/unlock visual on research rows — locked research greyed out (0x666666) with lock icon prefix; selection highlight turns red-tinted for locked entries.
- [DONE] Active research name display — shows the running research name (tier-colored) above the progress bar.
- [DONE] Drive contents tooltip — verified: DriveItem.appendHoverText shows tier, capacity (X/max or unlimited), bullet-pointed recipe IDs, and FULL indicator.
- [DONE] Animated progress bar — smooth green gradient bar in renderBg(); unfilled bg drawn first, bar fills proportionally.
- [DONE] Sync infrastructure — completed research sent to client via menu buffer (openMenu → FriendlyByteBuf); BE syncs active state via getUpdateTag/getUpdatePacket.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[DONE — Phase 7: Content & Data]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

- [DONE] Full research tree: 21 research definitions across all functional tiers (UNSTABLE→SELF_AWARE) with coherent prerequisite graph, 7 categories (signals, circuits, energy, materials, optics, computing, temporal, convergence).
  - UNSTABLE: unstable_signal, fragmented_data
  - BASIC: basic_circuit, energy_handling, material_synthesis, basic_optics
  - ADVANCED: advanced_processor, quantum_resonance, alloy_fabrication, photonic_amplifier, neural_interface
  - PRECISE: precision_engineering, waveform_analysis, nanostructures, temporal_calibration, biophotonic_matrix
  - FLAWLESS: dimensional_folding, molecular_assembly, cognitive_framework, zero_point_energy
  - SELF_AWARE: singularity_core, transcendent_logic, omniscient_matrix

- [DONE] Full recipe set: 35 drive_crafting recipe JSONs covering every recipe pool entry in the research tree, scaling from basic vanilla items (repeaters, chains) up through endgame rewards (elytra, dragon egg, nether stars).

- [DONE] Research categories field: optional "category" string in ResearchDefinition JSON, parsed by ResearchManager. Screen groups entries by category with collapsible-style headers (▸ category). Tooltip shows category. Categories: signals, circuits, energy, materials, optics, computing, temporal, convergence.

- [DONE] Weighted recipe pool: recipe_pool supports both plain string ("id") and object ({"id": "...", "weight": 3}) entries. WeightedRecipe record added. ResearchDefinition.pickWeightedRecipe() uses weighted random selection. Block entity completeResearch() calls pickWeightedRecipe() instead of uniform random.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[DONE — Phase 8: Audio / Visual Feedback]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

- [DONE] Research complete sound: plays SoundEvents.PLAYER_LEVELUP at the block when research finishes (server-side). Spawns HAPPY_VILLAGER + COMPOSTER particles via ServerLevel.sendParticles(). Implemented in ResearchTableBlockEntity.completeResearch().

- [DONE] Research start sound: plays SoundEvents.UI_BUTTON_CLICK at the block when research successfully starts (server-side). Implemented in ResearchTableBlockEntity.tryStartResearch().

- [DONE] Block ambient sound: ResearchStationSoundInstance (extends AbstractTickableSoundInstance) plays a looping beacon hum (SoundEvents.BEACON_AMBIENT, vol 0.25, pitch 0.6) at the block while research is active. ClientSoundHandler (subscribes to LevelTickEvent.Post) scans nearby block entities every 40 ticks and starts/stops instances automatically.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[DONE — Phase 9: Mod Compatibility & Polish]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

- [DONE] JEI/REI integration: compileOnly JEI dependency (mezz.jei 19.21.0.247, 1.21.1 NeoForge API). DriveCraftingCategory shows drive + ingredients → result with tooltip showing required recipe_id. ResearchCubeJEIPlugin (@JeiPlugin) registers the category, loads all drive_crafting recipes, adds Research Station info page and recipe catalyst. Located in compat/jei/ package.

- [DONE] Loot table & data gen audit: added loot table at data/researchcube/loot_table/blocks/research_station.json (drops itself with survives_explosion condition). All blockstates, block models, item models, and item textures verified complete and present.

- [DONE] Research book item: ResearchBookItem (creative tab, stacksTo(1)) opens a read-only ResearchBookScreen. Server sends OpenResearchBookPacket (server→client) with player's completed research set. Screen shows all research grouped by tier with ✔/✘ completion status, hover tooltips with full details (description, costs, prerequisites, recipes). Uses vanilla knowledge_book texture. Registered in ModItems, ModCreativeTabs, ModNetworking, and en_us.json.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Design Decisions (resolve before implementing dependent phases)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

- [RESOLVED] Completed research scope: implemented as per-player via ResearchSavedData (SavedData). Each player UUID has their own Set<ResourceLocation> of completed research.

- [RESOLVED] Drive reusability: drive PERSISTS after a drive_crafting recipe is used and the recipe_id is NOT removed — the same recipe can be crafted repeatedly as long as the ingredients are available. DriveCraftingRecipe.getRemainingItems() returns the drive unchanged; DriveCraftingTableMenu.onResultTaken() no longer calls NbtUtil.removeRecipe(). NbtUtil.removeRecipe() is kept for potential future use (e.g. Research Chip).

- [RESOLVED] Research failure / risk: no risk system. IRRECOVERABLE-tier research always completes cleanly with no corruption or destruction chance.

- [RESOLVED] [MAJOR] Multi-player research sharing: per-team. Players in the same Minecraft scoreboard team share one completed-research pool. ResearchSavedData must be refactored from UUID-keyed to team-name-keyed (with UUID fallback for players not in a team). Requires design + implementation approval before touching.

- [RESOLVED] Multi-tier Research Stations: one universal Research Station handles all tiers forever. No tiered station blocks will be added.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PHASE 10 — UI & Visual Improvements
(Self-contained improvements; no new systems required. Do non-MAJOR items first.)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

- [DONE] Bigger Research Station UI: expanded screen from 176×166 to 280×222. Research list now 130px wide with 8 visible rows (was 50px/3 rows). Progress bar widened to 106px. Start/Stop buttons are full-sized. Programmatic background rendering with bevelled panels replaces texture dependency. Slot positions updated in both Menu and Screen. Player inventory centered in the wider layout.

- [DONE] Research Station dynamic GeckoLib visuals per cube tier: ResearchStationRenderer overrides renderRecursively() to detect Brain bone hierarchy (Brain, center, b1–b8). When a CubeItem is in the cube slot, the brain bones are tinted with the tier's RGB color (ARGB packed) and rendered at full brightness (LightTexture.FULL_BRIGHT) for an emissive glow effect. A subtle pulsing sine wave (0.7–1.0 amplitude, ~800ms period) modulates the color brightness. ResearchTableBlockEntity.getCubeTier() reads the cube slot client-side (synced via getUpdateTag). No cube → default rendering; each tier (UNSTABLE→SELF_AWARE) shows its distinct color accent on the floating brain.

- [DONE] Custom Drive Crafting Table block: DriveCraftingTableBlock + DriveCraftingTableBlockEntity (10 slots: 1 drive + 3x3 grid, persistent inventory, drops on break) + DriveCraftingTableMenu (drive slot, crafting grid, result slot with live recipe matching via combined CraftingInput, ingredient consumption + recipe ID stripping on craft, shift-click support) + DriveCraftingTableScreen (programmatic bevelled-panel rendering matching mod style, slot visuals, arrow, result highlight, drive tooltip). Registered in ModBlocks, ModBlockEntities, ModMenus, ModItems (block item), ModCreativeTabs, ModClientEvents. Blockstate, block model (cube with 4 textures), item model, loot table (drops self), 16x16 placeholder textures (top/side/front/bottom), lang entries. JEI catalyst registered. Build verified.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[DONE — PHASE 11: Thinking Fluid System]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

- [DONE] [AI] Thinking Fluid tiers: 4 custom fluids (Thinking, Pondering, Reasoning, Imagination) registered via DeferredRegister<Fluid> with FluidType + Source + Flowing variants. Each has a matching bucket item (ResearchFluidBucketItem, prevents world placement). Client fluid extensions use vanilla water textures with custom tint colors (cyan/purple/gold/pink). NeoForge fluid_container bucket models. Registered in ModFluids, ModItems, ModCreativeTabs, ModClientEvents.

- [DONE] [AI] Fluid textures + models: IClientFluidTypeExtensions registered per fluid type. Bucket item models use neoforge:fluid_container loader. No separate PNG textures needed — vanilla water_still/water_flow with tint.

- [DONE] [AI] Fluid tank in Research Station BE: internal FluidTank (8000 mB capacity, filtered to 4 research fluids only). Persisted in NBT. Bucket input/output slots (8/9) auto-process fluid buckets every tick. Fluid cost validated and drained in tryStartResearch(). Refunded on cancel. Capability registered (Capabilities.FluidHandler.BLOCK) in ResearchCubeMod.

- [DONE] [AI] Research Station fluid UI: vertical fluid gauge (12×46px, colored by fluid type, fills bottom-to-top). 2 bucket slots with input/output indicators. "Wipe" button voids tank contents (sends WipeTankPacket). Fluid gauge tooltip shows fluid name, amount/capacity, and hint text. Fluid cost shown in research row tooltip.

- [DONE] [AI] Fluid-gated research: optional "fluid_cost" field in ResearchDefinition JSON (e.g. {"fluid": "researchcube:pondering_fluid", "amount": 1000}). ResearchManager parses it. tryStartResearch() validates and drains the tank. Fluid cost displayed in tooltip. All 23 research definitions updated: UNSTABLE=500mB thinking, BASIC=1000mB thinking, ADVANCED=1000mB pondering, PRECISE/FLAWLESS=2000mB reasoning, SELF_AWARE=4000mB imagination.

- [DONE] [AI] Fluid crafting/obtaining: 4 shapeless vanilla crafting recipes for fluid tier progression. water_bucket + 2 redstone → Thinking Fluid Bucket. Thinking + 2 glowstone_dust → Pondering. Pondering + 2 blaze_powder → Reasoning. Reasoning + ender_pearl + chorus_fruit → Imagination. Lang entries for all bucket items and fluid types added to en_us.json.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[DONE — PHASE 12 — Recipe Discoverability & JEI/Book Improvements]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

- [DONE] [AI] JEI drive crafting: show unlocking research name
  DriveCraftingCategory.setRecipe() now resolves which ResearchDefinition has the recipe_id
  in its pool (via RecipeOutputResolver.findResearchForRecipe()) and appends a tooltip line:
  "Unlocked by: <Research Display Name> (<Tier>)". Lists all matching research entries.

- [DONE] [AI] JEI drive crafting: pre-loaded drive as ingredient
  Instead of cycling all bare drives, the JEI category now creates a single ItemStack of
  the correct tier drive (resolved from the unlocking research's tier) with the recipe_id
  pre-loaded via NbtUtil.addRecipe(). Players can use JEI "show uses" on a filled drive.

- [DONE] [AI] Research Book: show recipe output items instead of raw IDs
  ResearchBookScreen tooltip now shows "Possible Rewards:" followed by each recipe resolved
  to its output item name + count via RecipeOutputResolver. Falls back to raw ID if unresolvable.

- [DONE] [AI] Research Station screen: show recipe output items instead of raw IDs
  ResearchTableScreen tooltip now shows "Rewards: Repeater ×4 or Comparator ×2" instead of
  raw recipe IDs. Uses RecipeOutputResolver.formatOutput() for each pool entry.

- [DONE] [AI] Drive item tooltip: resolve recipe IDs to output item names
  DriveItem.appendHoverText() now shows resolved output names in green with raw recipe ID
  shown in dark gray on advanced/shift hover. Falls back to raw ID if resolution fails.
  Shared RecipeOutputResolver utility class created in com.researchcube.util.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[DONE — PHASE 13 — Shaped Drive Crafting Support]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

- [DONE] [AI] DriveCraftingRecipe: add optional shaped mode
  Extended DriveCraftingRecipe with optional ShapedRecipePattern support. When
  "pattern" + "key" are present in JSON, the recipe uses shaped matching via
  ShapedRecipePattern.matches(); otherwise it falls back to shapeless logic.
  Added isShaped() flag, matchesShapedMode() and matchesShapelessMode() methods.
  Drive is detected and excluded from the pattern match (placed anywhere in grid).

  Example shaped JSON:
  {
    "type": "researchcube:drive_crafting",
    "recipe_id": "researchcube:shaped_test_recipe",
    "pattern": ["RR ", "II ", "   "],
    "key": {
      "R": { "item": "minecraft:redstone" },
      "I": { "item": "minecraft:iron_ingot" }
    },
    "result": { "id": "minecraft:repeater", "count": 4 }
  }

- [DONE] [AI] DriveCraftingRecipeSerializer: parse shaped fields
  DriveCraftingRecipeSerializer uses a custom MapCodec with decode() that checks for
  "pattern" key presence. If present, decodes via ShapedRecipePattern.MAP_CODEC;
  otherwise uses the shapeless ingredients list. StreamCodec writes/reads a boolean
  flag followed by either ShapedRecipePattern.STREAM_CODEC or ingredient list.

- [DONE] [AI] DriveCraftingTableMenu: respect shaped mode
  DriveCraftingTableMenu.updateResult() now builds a 4×3 CraftingInput layout where
  columns 0-2 are the 3×3 grid and column 3 holds the drive. This preserves positional
  matching for shaped recipes while still including the drive for detection.
  consumeGridIngredientsShaped() and consumeGridIngredientsShapeless() handle ingredient
  consumption correctly based on recipe type.

- [DONE] [AI] JEI drive crafting category: shaped layout
  DriveCraftingCategory.setRecipe() detects recipe.isShaped() and switches layout:
  shaped recipes render in a 3×3 grid matching the pattern dimensions; shapeless
  recipes use the previous 4×2 flat arrangement. Background height increased to 72px
  to accommodate the 3×3 grid.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[DONE — PHASE 14 — Quality of Life & Content Extras]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

- [DONE] [AI] NeoForge common config file
  Added ModConfig (COMMON) with researchDurationMultiplier (default 1.0),
  researchCostMultiplier (default 1.0), enableTeamSharing (default true),
  and processingDurationMultiplier (default 1.0). Applied in BE serverTick().

- [DONE] [AI] Advancements on research completion
  Created CompleteResearchTrigger (custom CriterionTrigger) + ModCriterionTriggers registry.
  Added 21 advancement JSONs under data/researchcube/advancement/research/ for all
  research entries. Fires from ResearchTableBlockEntity.completeResearch().

- [DONE] [AI] Research export chip item
  Added ResearchChipItem with CustomData storage. Right-click Research Station encodes
  a completed research ID; right-clicking again on another Research Station decodes it.

- [DONE] [AI] Research Station block: comparator output
  Implemented getAnalogOutputSignal() on ResearchTableBlock. Returns 0 when idle,
  1–14 scaled by progress, 15 on completion.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[DONE — PHASE 15 — Datapack Documentation]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

- [DONE] [AI] Created DATAPACK.md guide:
  Comprehensive developer guide covering research definition JSON schema with examples,
  drive crafting recipe schema (shapeless + shaped), prerequisites syntax (AND/OR trees),
  tier reference table, weighted recipe pools, configuration, common patterns,
  troubleshooting, and file structure.

- [DONE] [AI] Created example_datapack/:
  Complete example datapack with 3 interconnected crystal researches demonstrating
  prerequisite chains (basic_crystals → refined_crystals → pure_crystals) plus
  4 drive crafting recipes showing both shapeless and shaped patterns.

- [DONE] [AI] Updated README.md:
  Added Quick Start sections for players and pack developers with links to DATAPACK.md.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[DONE — PHASE 16 — Processing Crafting Station]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

- [DONE] [AI] ProcessingRecipe + ProcessingRecipeSerializer:
  New recipe type with up to 16 item inputs, 2 fluid inputs, 8 item outputs, 1 fluid output.
  MapCodec + StreamCodec serializer. ProcessingFluidStack helper record for fluid serialization.

- [DONE] [AI] ProcessingStationBlock + ProcessingStationBlockEntity:
  24-slot inventory (16 input + 8 output), 3 FluidTanks (2 input + 1 output, 8000 mB each).
  Server-side ticking with config multiplier. NBT persistence. Update packets.
  getCombinedFluidHandler() for pipe interactions. Comparator output.

- [DONE] [AI] ProcessingStationMenu + ProcessingStationScreen:
  Programmatic bevelled panel rendering. 4x4 input grid, 2x4 output grid, 3 fluid gauges,
  progress bar, Start button. ContainerData sync for progress and fluid amounts.

- [DONE] [AI] StartProcessingPacket:
  Client→server packet using StreamCodec.composite pattern. Validates recipe match,
  consumes inputs, starts processing. Logs WARN on validation failure.

- [DONE] [AI] Registry updates:
  ModRecipeTypes (PROCESSING), ModRecipeSerializers (PROCESSING), ModBlocks (PROCESSING_STATION),
  ModBlockEntities (PROCESSING_STATION), ModMenus (PROCESSING_STATION), ModItems (block item),
  ModCreativeTabs, ModNetworking, ModClientEvents all updated. Fluid capability registered
  in ResearchCubeMod.

- [DONE] [AI] JEI Integration:
  ProcessingCategory renders 4x4 input grid, fluid inputs, 2x4 output grid, fluid output.
  Registered in ResearchCubeJEIPlugin with recipe catalyst. Info page added.

- [DONE] [AI] Assets:
  Blockstate, block model (uses vanilla blast_furnace textures as placeholder), item model,
  loot table, lang entries for block and item.

- [DONE] [AI] Example recipe:
  processing_iron_compression.json demonstrating item + fluid inputs → item output.

- [DONE] [AI] Processing Station GUI enhancement pass:
  Expanded to a larger 238x208 layout with clearer panel grouping, repositioned slot grids,
  improved fluid/progress visuals, in-screen status text, and hover tooltips for tanks and progress.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[DONE — PHASE 17 — Research Tree Visualization Screen]
(Visual tree-graph rendering of research prerequisites as alternative to list view.)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

- [DONE] [AI] ResearchTreeScreen (new client screen):
  - Parse all research from ResearchRegistry + prerequisite graph
  - Auto-layout: breadth-first hierarchical or force-directed (algorithm TBD)
  - Render as nodes (tier-colored circles/boxes) + edges (prerequisite links)
  - AND/OR prerequisites visually distinct (different colors or styles)
  - Hover → tooltip with tier, name, costs, completion status (✔/✘/locked)
  - Click node → select research
  - "Start Research" button (same as list view)
  - Toggle button or option menu to switch between tree view / list view

- [DONE] [AI] Integrate toggle into current ResearchTableScreen or add new screen selector

- [DONE] [AI] Handle edge cases: large research trees, overlapping nodes, single-node selections

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[DONE — PHASE 18 — EMI Integration]
(EMI is a popular alternative recipe viewer; full parity with the existing JEI plugin.)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

- [DONE] [AI] EMI plugin entry point: ResearchCubeEMIPlugin (@EmiEntrypoint, implements EmiPlugin)
  - Registers DriveCrafting + Processing categories, workstations, recipes, and info pages.

- [DONE] [AI] EMI DriveCrafting category (EmiDriveCraftingRecipe):
  - Pre-loaded drive with recipe_id, shaped/shapeless layouts, "Unlocked by" tooltip
    with completion indicator (✔/✘ via ClientResearchData).

- [DONE] [AI] EMI Processing Station category (EmiProcessingRecipe):
  - 4×4 input grid, fluid inputs, 2×4 output grid, fluid output, arrow with duration tooltip.

- [DONE] [AI] EMI Research Station info page:
  - Multi-step workflow guide, fluid tiers, drive capacity table.

- [DONE] [AI] compileOnly EMI dependency in build.gradle + optional dependency in neoforge.mods.toml.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[DONE — PHASE 19 — JEI & EMI UI Improvements]
(Polish the existing JEI plugin and the new EMI plugin for clarity and completeness.)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

- [DONE] [AI] JEI DriveCrafting category: visual overhaul
  - draw() renders bevelled panel background, "Drive" label, slot outlines, arrow,
    and completion indicator (✔/✘) in the corner.

- [DONE] [AI] JEI Processing Station category: visual overhaul
  - draw() renders bevelled panel, "Inputs"/"Outputs" headers, slot outlines,
    arrow with duration text, fluid slot outlines.

- [DONE] [AI] JEI/EMI: Research Station info page — multi-page guide
  - Research workflow steps, fluid tier overview, drive capacity table per tier.

- [DONE] [AI] JEI: "Show recipes" on Drive item via subtype interpreter
  - registerItemSubtypes() registers all 7 drive items with a custom interpreter
    that keys on sorted recipe IDs. Pre-loaded drives in categories work with "show uses".

- [DONE] [AI] JEI/EMI: Research completion status indicator
  - JEI DriveCraftingCategory tooltip and draw() overlay show green ✔ or red ✘
    based on ClientResearchData.isCompleted(). EMI EmiDriveCraftingRecipe already
    had ✔/✘ in buildDriveTooltip().

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[DONE — PHASE 20 — User Visibility & Usability QoL]
(Features that reduce friction and make the mod's state readable at a glance.)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

- [DONE] [AI] Research progress HUD overlay
  ResearchHudOverlay renders a compact 140×28 panel in a configurable screen corner
  showing research name (tier-colored), progress bar, and ETA. Config options:
  showResearchHUD (default true), researchHUDCorner (0–3, default top-right).
  SyncResearchProgressPacket sent every 20 ticks from ResearchTableBlockEntity.serverTick()
  and cleared on research complete/cancel.

- [DONE] [AI] Jade / WAILA block tooltip integration
  ResearchCubeJadePlugin, ResearchStationProvider, ProcessingStationProvider.
  Shows "Researching: <name> (XX%)" or "Idle" + fluid amounts.

- [DONE] [AI] In-screen search bar in ResearchTableScreen and ResearchBookScreen
  Client-side text filter by name, category, or tier. Escape clears.

- [DONE] [AI] Drive inspector screen
  DriveInspectorScreen lists all stored recipes resolved to output item names + counts,
  with item icons. Opened via DriveItem.use() on right-click.

- [DONE] [AI] Patchouli in-game guidebook integration
  Patchouli book definition + 4 categories (Getting Started, Fluids, Drives & Crafting,
  Processing) + 9 entries with multi-page content covering research station workflow,
  tiers, all 4 fluids with crafting references, drives, drive crafting table,
  and processing station. Book auto-registered by Patchouli as researchcube:guide.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[TODO — PHASE 21 — Research Idea Chips (Pack-Dev Research Gates)]
(Allows pack developers to gate specific research behind a custom broken drive "idea chip"
item with a unique name and/or NBT. The chip is placed in a new dedicated slot in the
Research Station and is consumed when research begins. Distribution to players is handled
entirely by the pack dev via quests, loot tables, or other means.)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

- [x] [AI] ResearchDefinition: add optional `idea_chip` field
  ResearchDefinition gains an Optional<ItemStack> ideaChip field (default Optional.empty()).
  The field is parsed from an optional "idea_chip" JSON object in the research definition file:
    {
      "idea_chip": {
        "item": "researchcube:metadata_broken",
        "components": {
          "minecraft:custom_name": "{\"text\":\"Idea: Advanced Alloys\",\"italic\":false}",
          "minecraft:custom_data": { "researchcube_chip_id": "advanced_alloys" }
        }
      }
    }
  Codec: use ItemStack.CODEC (or a manual MapCodec) wrapped in Codec.optionalField().
  ResearchManager must pass through the new field when constructing ResearchDefinition.

- [x] [AI] ItemStack partial-match helper utility
  Add a static helper IdeaChipMatcher.matches(ItemStack required, ItemStack candidate):
    - Item registry name must be equal.
    - For each DataComponentType declared in required.getComponents(), the candidate must
      have the same value for that component. Components present only in the candidate
      but not in required are ignored (partial match).
  This lets pack devs declare only the components they care about (e.g. just a custom name)
  without having to enumerate every default component on the item.
  Place in com.researchcube.util.IdeaChipMatcher.

- [x] [AI] ResearchTableBlockEntity: idea chip inventory slot
  Add one new inventory slot (index 9, shifting previous slot count from 9 to 10).
  Slot is unrestricted by item type (any item may be placed there by the player).
  In tryStartResearch(): after all existing validation, if the selected research definition
  has a non-empty ideaChip:
    - Retrieve the item in slot 9.
    - Call IdeaChipMatcher.matches(required, candidate). If false → send failure feedback
      to the player ("Missing idea chip: <chip display name>") and return without starting.
    - If true → shrink slot 9 stack by 1 (consume the chip) and proceed normally.
  In cancelResearchWithRefund(): the idea chip is NOT refunded (it was the entry price;
  research was at least started). Add a note comment to this effect.
  NBT persistence: slot 9 is saved/loaded with the rest of the inventory automatically
  (ContainerHelper.saveAllItems / loadAllItems already iterates all slots by index, so no
  extra NBT changes needed as long as the slot count constant is updated).

- [x] [AI] ResearchTableMenu: register the new slot
  Increment slot count constant from 9 to 10. Add the idea chip slot to the container
  with a SlotItemHandler at slot index 9. Position: TBD during screen layout step below.
  Ensure the slot is included in the shift-click quick-move logic.

- [x] [AI] ResearchTableScreen: render the idea chip slot + contextual feedback
  Add a dedicated visual slot to the Research Station GUI for the idea chip (index 9).
  Suggested position: below the drive slot or next to the Start button, clearly separated
  from the cost item slots. Render a subtle "chip" icon or label ("Idea") above the slot.

  Contextual behavior:
    - When the currently selected research has no idea_chip requirement: render the slot
      with a dimmed/greyed overlay and a tooltip "No idea chip required for this research."
    - When the requirement exists and the slot is empty or mismatched: render a red-tinted
      border or highlight on the slot and disable (grey out) the Start button with an
      additional tooltip line "Requires idea chip: <chip display name>".
    - When the requirement is satisfied: slot renders normally, Start button is enabled.

  The slot state is determined client-side by comparing the idea chip requirement (synced
  from the server) against the current slot contents (synced automatically by the container).

- [x] [AI] Network sync: send ideaChip to client
  ResearchTableScreen needs to show the tooltip name of the required chip client-side.
  Options (pick simplest):
    a) Include ideaChip ItemStack in the existing openMenu FriendlyByteBuf payload
       (alongside the completed-research set already sent there). Rebuild when the player
       selects a different research entry via a new small S→C packet or by re-opening the
       menu. Preferred if the menu is already rebuilt on research selection.
    b) Add a new SyncSelectedResearchPacket (server→client) that carries the full
       ResearchDefinition (or just id + ideaChip) for the currently selected research,
       sent whenever the selection changes. Store it in ResearchTableScreen.
  Either way the client must be able to read the required chip's display name and
  components to compare against the slot contents and render the tooltip correctly.

- [x] [AI] Broken drive item: ensure it can carry arbitrary components (no-op if already works)
  Verify that metadata_broken (BrokenDriveItem or however the broken drive is registered)
  does not strip or override custom_name / custom_data components. If it does, ensure these
  pass through cleanly so pack devs can attach names and data via item_modifiers or
  give commands without the item resetting them.

- [x] [AI] Update example research JSONs + DATAPACK.md
  Add idea_chip to one example research definition (e.g. a new "gated_example" or an
  amendment to an existing one) to validate end-to-end functionality.
  Add an "Idea Chips" section to DATAPACK.md explaining:
    - JSON schema for the idea_chip field.
    - How to create a custom chip via /give, item_modifier loot function, or datapack items.
    - Partial-match semantics (only declared components are checked).
    - That the chip is consumed on research start and is NOT refunded on cancel.
    - Recommended practice: use a unique minecraft:custom_data tag as a stable ID, and
      set a human-readable minecraft:custom_name for player-facing display.

- [x] [AI] Update example_datapack/ with a gated research example
  Add a research definition that uses idea_chip and a matching drive crafting recipe.
  Include a sample loot_table or item_modifier JSON showing how a pack dev would
  distribute the chip (e.g. as a reward item in a loot table).