feat: add idea chip functionality for gated research in Research Station to the todo.lock

Author: MrSilly07

todo.lock

@@ -403,3 +403,107 @@ PHASE 10 — UI & Visual Improvements
   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.)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+- [ ] [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.
+
+- [ ] [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.
+
+- [ ] [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).
+
+- [ ] [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.
+
+- [ ] [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).
+
+- [ ] [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.
+
+- [ ] [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.
+
+- [ ] [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.
+
+- [ ] [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).