feat: add idea chip feature to research mechanics

- Introduced an optional `idea_chip` field in `ResearchDefinition` to gate research.
- Implemented `IdeaChipMatcher` for partial matching of idea chips based on item components.
- Updated `ResearchTableBlockEntity` to include an idea chip inventory slot and validate its presence when starting research.
- Modified `ResearchTableMenu` to register the new idea chip slot.
- Enhanced `ResearchTableScreen` to render the idea chip slot with contextual feedback and tooltips.
- Added command `/researchcube giveChip` to distribute idea chips to players.
- Updated example research JSON to include an idea chip requirement.
- Documented the idea chip feature in `DATAPACK.md` for clarity on usage and implementation.

Author: MrSilly07

.github/copilot-instructions.md

@@ -47,9 +47,9 @@
 | Package | Purpose |
 |---|---|
 | `com.researchcube` | `ResearchCubeMod` — entry point, `rl()` helper, DeferredRegister wiring, `IFluidHandler` capability registration |
-| `block` | `ResearchTableBlock` (opens menu on right-click), `ResearchTableBlockEntity` (GeoBlockEntity, ticking, 10-slot inventory + FluidTank, `getUpdateTag`/`getUpdatePacket` for client sync), `DriveCraftingTableBlock`, `DriveCraftingTableBlockEntity`, `ProcessingStationBlock`, `ProcessingStationBlockEntity` |
+| `block` | `ResearchTableBlock` (opens menu on right-click), `ResearchTableBlockEntity` (GeoBlockEntity, ticking, 11-slot inventory + FluidTank, `getUpdateTag`/`getUpdatePacket` for client sync), `DriveCraftingTableBlock`, `DriveCraftingTableBlockEntity`, `ProcessingStationBlock`, `ProcessingStationBlockEntity` |
 | `item` | `DriveItem` (tiered, stores recipe IDs in CustomData, `isFull()` capacity check, foil effect, opens `DriveInspectorScreen` on right-click), `CubeItem` (tiered, validation only), `ResearchBookItem` (opens research book screen via packet), `ResearchChipItem`, `ResearchFluidBucketItem` (custom bucket for research fluids) |
-| `menu` | `ResearchTableMenu` — 10 BE slots + player inventory, 4-value `SimpleContainerData`, `completedResearch` set from buf; `DriveCraftingTableMenu` — drive crafting container; `ProcessingStationMenu` — processing station container |
+| `menu` | `ResearchTableMenu` — 11 BE slots + player inventory, 4-value `SimpleContainerData`, `completedResearch` set from buf; `DriveCraftingTableMenu` — drive crafting container; `ProcessingStationMenu` — processing station container |
 | `client` | `ModClientEvents` — registers screens + GeckoLib renderer + sound (Dist.CLIENT, MOD bus); `ClientSoundHandler` — starts/stops `ResearchStationSoundInstance`; `ClientResearchData` — client-side cache of completed research for JEI/EMI integration; `ResearchHudOverlay` — on-screen HUD showing active research progress |
 | `client/screen` | `ResearchTableScreen` — scrollable research list with tier colors + lock icons, prereq tooltip, fluid gauge, gradient progress bar, Start/Stop buttons; `DriveCraftingTableScreen`; `ProcessingStationScreen`; `ResearchBookScreen` — read-only research encyclopedia; `ResearchTreeScreen` — tree visualization; `DriveInspectorScreen` — shows recipes stored on a drive; `ScreenRenderHelper` — shared rendering utilities |
 | `client/renderer` | `ResearchStationModel`, `ResearchStationRenderer` — GeckoLib geo/animation/texture wiring |
@@ -59,11 +59,11 @@
 | `compat/jade` | `ResearchCubeJadePlugin`, `ResearchStationProvider`, `ProcessingStationProvider` — Jade block overlays |
 | `network` | `StartResearchPacket`, `CancelResearchPacket`, `WipeTankPacket`, `OpenResearchBookPacket`, `StartProcessingPacket` (all client→server); `SyncResearchProgressPacket` (server→client); `ModNetworking` (PayloadRegistrar) |
 | `recipe` | `DriveCraftingRecipe`, `DriveCraftingRecipeSerializer`, `ProcessingRecipe`, `ProcessingRecipeSerializer`, `ProcessingFluidStack` |
-| `research` | `ResearchDefinition` (id, tier, duration, prerequisites, itemCosts, fluidCost, recipePool, name, description, category), `ResearchRegistry`, `ResearchManager`, `ResearchTier` (with `maxRecipes` and `getColor()`), `ItemCost`, `FluidCost`, `WeightedRecipe`, `ResearchSavedData` |
+| `research` | `ResearchDefinition` (id, tier, duration, prerequisites, itemCosts, fluidCost, recipePool, name, description, category, ideaChip), `ResearchRegistry`, `ResearchManager`, `ResearchTier` (with `maxRecipes` and `getColor()`), `ItemCost`, `FluidCost`, `WeightedRecipe`, `ResearchSavedData` |
 | `research/prerequisite` | `Prerequisite` interface (with `describe()`), `AndPrerequisite`, `OrPrerequisite`, `SinglePrerequisite`, `NonePrerequisite`, `PrerequisiteParser` |
 | `research/criterion` | `CompleteResearchTrigger` — advancement criterion fired on research completion |
 | `registry` | `ModItems`, `ModBlocks`, `ModBlockEntities`, `ModMenus`, `ModCreativeTabs`, `ModRecipeTypes`, `ModRecipeSerializers`, `ModFluids`, `ModConfig`, `ModCriterionTriggers` |
-| `util` | `NbtUtil` (CustomData read/write), `TierUtil` (canResearch validation), `RecipeOutputResolver` |
+| `util` | `NbtUtil` (CustomData read/write), `TierUtil` (canResearch validation), `RecipeOutputResolver`, `IdeaChipMatcher` (partial ItemStack matching for idea chip validation) |
 | `event` | `ModServerEvents` (AddReloadListenerEvent) |
 
 ## Critical workflows
@@ -88,7 +88,7 @@
 - Register new game objects using `DeferredRegister` in `registry/Mod*` classes, then ensure they are registered in `ResearchCubeMod` constructor.
 - **Server authority**: never start/complete/cancel research from client code. Client screens send packets; server validates.
 - Preserve slot semantics in `ResearchTableBlockEntity` / `ResearchTableMenu`:
-  - slot 0 = drive, slot 1 = cube, slots 2–7 = item costs, slot 8 = bucket_in, slot 9 = bucket_out (`SLOT_DRIVE=0`, `SLOT_CUBE=1`, `COST_SLOT_START=2`, `SLOT_BUCKET_IN=8`, `SLOT_BUCKET_OUT=9`, `TOTAL_SLOTS=10`).
+  - slot 0 = drive, slot 1 = cube, slots 2–7 = item costs, slot 8 = bucket_in, slot 9 = bucket_out, slot 10 = idea_chip (`SLOT_DRIVE=0`, `SLOT_CUBE=1`, `COST_SLOT_START=2`, `SLOT_BUCKET_IN=8`, `SLOT_BUCKET_OUT=9`, `SLOT_IDEA_CHIP=10`, `TOTAL_SLOTS=11`).
   - When iterating cost slots, always loop `COST_SLOT_START` to `SLOT_BUCKET_IN` (exclusive), i.e. slots 2–7 only. Never include bucket slots in item-cost validation or consumption.
   - The block entity also holds a `FluidTank` (capacity `TANK_CAPACITY = 8000` mB). Fluid cost is validated and drained separately from item costs.
 - Enforce tier rules through `TierUtil.canResearch(cubeTier, driveTier, researchTier)` — cube tier ≥ research tier AND drive tier == research tier.

DATAPACK.md

@@ -0,0 +1,156 @@
+# ResearchCube Datapack Guide
+
+## Research Definitions
+
+Research definitions are JSON files placed in `data/{namespace}/research/{name}.json`. The file path determines the research ID (e.g., `data/example/research/crystal_analysis.json` → `example:crystal_analysis`).
+
+### JSON Schema
+
+```json
+{
+  "name": "Display Name",
+  "description": "Short description shown in tooltips.",
+  "category": "grouping_category",
+  "tier": "BASIC",
+  "duration": 1200,
+  "item_costs": [
+    { "item": "minecraft:redstone", "count": 16 }
+  ],
+  "fluid_cost": {
+    "fluid": "researchcube:thinking_fluid",
+    "amount": 1000
+  },
+  "idea_chip": {
+    "id": "researchcube:metadata_irrecoverable",
+    "components": {
+      "minecraft:custom_name": "\"Idea: My Research\"",
+      "minecraft:custom_data": { "my_chip_id": "my_research" }
+    }
+  },
+  "prerequisites": {
+    "type": "ALL",
+    "values": ["namespace:other_research"]
+  },
+  "recipe_pool": [
+    "namespace:recipe_id",
+    { "id": "namespace:other_recipe", "weight": 3 }
+  ]
+}
+```
+
+### Fields
+
+| Field | Required | Description |
+|---|---|---|
+| `tier` | Yes | Research tier: `UNSTABLE`, `BASIC`, `ADVANCED`, `PRECISE`, `FLAWLESS`, `SELF_AWARE` |
+| `duration` | Yes | Duration in game ticks (20 ticks = 1 second) |
+| `name` | No | Human-readable display name (defaults to file name) |
+| `description` | No | Short description shown in tooltips |
+| `category` | No | Grouping category for the research list UI |
+| `item_costs` | No | Array of `{ "item": "<item_id>", "count": <n> }` |
+| `fluid_cost` | No | `{ "fluid": "<fluid_id>", "amount": <mB> }` |
+| `idea_chip` | No | ItemStack gating this research (see Idea Chips section) |
+| `prerequisites` | No | Prerequisite structure (`ALL`, `ANY`, or single ID) |
+| `recipe_pool` | No | Array of recipe IDs (string or `{ "id": ..., "weight": ... }`) |
+
+### Research Tiers
+
+| Tier | Required Fluid | Required Cube |
+|---|---|---|
+| UNSTABLE | Thinking Fluid | cube_unstable+ |
+| BASIC | Thinking Fluid | cube_basic+ |
+| ADVANCED | Pondering Fluid | cube_advanced+ |
+| PRECISE | Reasoning Fluid | cube_precise+ |
+| FLAWLESS | Reasoning Fluid | cube_flawless+ |
+| SELF_AWARE | Imagination Fluid | cube_self_aware |
+
+The drive must exactly match the research tier. The cube must be equal or higher tier.
+
+---
+
+## Idea Chips
+
+Idea chips allow pack developers to gate specific research behind a custom item that
+is placed in a dedicated slot in the Research Station. The chip is **consumed when
+research begins** and is **NOT refunded on cancel**.
+
+### How It Works
+
+1. Add an `"idea_chip"` field to your research definition JSON.
+2. The field uses standard `ItemStack` codec format (`"id"` + optional `"components"`).
+3. When a player selects that research, the Research Station UI shows the idea chip
+   slot with a red border and tooltip indicating what chip is required.
+4. The player must place a matching item in the idea chip slot to enable the Start button.
+5. On research start, the chip is consumed (stack shrinks by 1).
+6. On cancel, item costs and fluid are refunded, but the idea chip is **not** refunded.
+
+### Partial-Match Semantics
+
+The idea chip uses **partial matching**: only the components explicitly declared in
+your JSON are checked. Components present on the player's item but not declared in
+the JSON are ignored.
+
+This means you can declare just a `custom_name` to match by name, or just
+`custom_data` to match by a stable tag, or both. Default item components (like
+`max_stack_size`) do not need to be listed.
+
+### Creating Chips for Players
+
+Pack devs distribute idea chips to players via quests, loot tables, or give commands.
+
+**Give command example:**
+```
+/give @p researchcube:metadata_irrecoverable[custom_name='"Idea: Forbidden Crystal"',custom_data={researchcube_chip_id:"forbidden_crystal"}]
+```
+
+**Item modifier (loot function):**
+```json
+{
+  "function": "minecraft:set_components",
+  "components": {
+    "minecraft:custom_name": "\"Idea: Forbidden Crystal\"",
+    "minecraft:custom_data": { "researchcube_chip_id": "forbidden_crystal" }
+  }
+}
+```
+
+### Recommended Practice
+
+- Use a unique `minecraft:custom_data` tag as a **stable ID** for matching
+  (e.g., `{ "researchcube_chip_id": "my_research" }`).
+- Set a human-readable `minecraft:custom_name` for **player-facing display**
+  (e.g., `"Idea: Advanced Alloys"`).
+- Using both ensures the chip is identifiable by players and reliably matched by the system.
+
+### Example Research Definition with Idea Chip
+
+```json
+{
+  "name": "Forbidden Crystal Synthesis",
+  "category": "materials",
+  "tier": "ADVANCED",
+  "duration": 4800,
+  "item_costs": [
+    { "item": "minecraft:amethyst_shard", "count": 16 },
+    { "item": "minecraft:diamond", "count": 4 }
+  ],
+  "fluid_cost": {
+    "fluid": "researchcube:pondering_fluid",
+    "amount": 2000
+  },
+  "idea_chip": {
+    "id": "researchcube:metadata_irrecoverable",
+    "components": {
+      "minecraft:custom_name": "\"Idea: Forbidden Crystal\"",
+      "minecraft:custom_data": { "researchcube_chip_id": "forbidden_crystal" }
+    }
+  },
+  "prerequisites": {
+    "type": "ALL",
+    "values": ["example:crystal_resonance"]
+  },
+  "recipe_pool": [
+    "example:resonant_crystal_recipe"
+  ]
+}
+```

example_datapack/data/example/research/forbidden_crystal.json

@@ -0,0 +1,29 @@
+{
+  "name": "Forbidden Crystal Synthesis",
+  "description": "A dangerous experiment requiring a special authorization chip to begin.",
+  "category": "materials",
+  "tier": "ADVANCED",
+  "duration": 4800,
+  "item_costs": [
+    { "item": "minecraft:amethyst_shard", "count": 16 },
+    { "item": "minecraft:diamond", "count": 4 }
+  ],
+  "fluid_cost": {
+    "fluid": "researchcube:pondering_fluid",
+    "amount": 2000
+  },
+  "idea_chip": {
+    "id": "researchcube:metadata_irrecoverable",
+    "components": {
+      "minecraft:custom_name": "\"Idea: Forbidden Crystal\"",
+      "minecraft:custom_data": { "researchcube_chip_id": "forbidden_crystal" }
+    }
+  },
+  "prerequisites": {
+    "type": "ALL",
+    "values": ["example:crystal_resonance"]
+  },
+  "recipe_pool": [
+    "example:resonant_crystal_recipe"
+  ]
+}

src/main/java/com/researchcube/block/ResearchTableBlockEntity.java

@@ -11,6 +11,7 @@
 import com.researchcube.research.criterion.CompleteResearchTrigger;
 import com.researchcube.util.NbtUtil;
 import com.researchcube.util.TierUtil;
+import com.researchcube.util.IdeaChipMatcher;
 import com.researchcube.network.SyncResearchProgressPacket;
 import net.minecraft.core.BlockPos;
 import net.minecraft.core.HolderLookup;
@@ -58,7 +59,10 @@
  * Slots:
  *   0 = Drive
  *   1 = Cube
- *   2+ = Item cost inputs (expandable)
+ *   2-7 = Item cost inputs
+ *   8 = Bucket input
+ *   9 = Bucket output
+ *   10 = Idea chip
  *
  * NBT:
  *   ActiveResearch: ResourceLocation string of current research
@@ -72,7 +76,8 @@ public class ResearchTableBlockEntity extends BlockEntity implements GeoBlockEnt
     public static final int COST_SLOT_START = 2;
     public static final int SLOT_BUCKET_IN = 8;
     public static final int SLOT_BUCKET_OUT = 9;
-    public static final int TOTAL_SLOTS = 10; // 2 fixed + 6 cost + 2 bucket slots
+    public static final int SLOT_IDEA_CHIP = 10;
+    public static final int TOTAL_SLOTS = 11; // 2 fixed + 6 cost + 2 bucket + 1 idea chip
     public static final int TANK_CAPACITY = 8000; // 8 buckets (in mB)
 
     // GeckoLib animation
@@ -297,6 +302,17 @@ public boolean tryStartResearch(String researchId, Set<String> completedResearch
             }
         }
 
+        // Validate idea chip (if defined)
+        if (definition.getIdeaChip().isPresent()) {
+            ItemStack required = definition.getIdeaChip().get();
+            ItemStack candidate = inventory.getStackInSlot(SLOT_IDEA_CHIP);
+            if (!IdeaChipMatcher.matches(required, candidate)) {
+                ResearchCubeMod.LOGGER.warn("[ResearchCube] Cannot start '{}': missing idea chip: {}",
+                        researchId, required.getHoverName().getString());
+                return false;
+            }
+        }
+
         // All checks passed — snapshot costs for potential refund, then consume
         this.consumedCosts = definition.getItemCosts();
         this.consumedFluidCost = fluidCost;
@@ -308,6 +324,11 @@ public boolean tryStartResearch(String researchId, Set<String> completedResearch
             fluidTank.drain(toDrain, IFluidHandler.FluidAction.EXECUTE);
         }
 
+        // Consume idea chip (not refunded on cancel — it is the entry price)
+        if (definition.getIdeaChip().isPresent()) {
+            inventory.getStackInSlot(SLOT_IDEA_CHIP).shrink(1);
+        }
+
         // Start research
         this.activeResearchId = researchId;
         this.startTime = level.getGameTime();
@@ -563,6 +584,7 @@ private void sendClearPacket(ServerLevel serverLevel, String key) {
     /**
      * Cancel active research and refund item costs back into cost slots.
      * Called from CancelResearchPacket handler.
+     * Note: the idea chip is NOT refunded — it was consumed as the entry price.
      */
     public void cancelResearchWithRefund() {
         if (!isResearching()) return;

src/main/java/com/researchcube/client/screen/ResearchBookScreen.java

@@ -294,6 +294,13 @@ private void renderEntryTooltip(GuiGraphics graphics, int mouseX, int mouseY, in
             }
         }
 
+        // Idea chip requirement
+        if (def.getIdeaChip().isPresent()) {
+            ItemStack chip = def.getIdeaChip().get();
+            tooltip.add(Component.literal("Idea Chip: " + chip.getHoverName().getString())
+                    .withStyle(s -> s.withColor(0xFFAA55)));
+        }
+
         // Prerequisites
         if (!(def.getPrerequisites() instanceof NonePrerequisite)) {
             boolean met = def.getPrerequisites().isSatisfied(completedResearch);