diff --git a/.AGENTS/CORE_MIGRATION_PLAN.md b/.AGENTS/CORE_MIGRATION_PLAN.md new file mode 100644 index 000000000..4cd33ef1a --- /dev/null +++ b/.AGENTS/CORE_MIGRATION_PLAN.md @@ -0,0 +1,1111 @@ +# CORE MIGRATION PLAN — Move-Abstract-Implement Cycle + +**Created:** 2026-03-15 +**Purpose:** Exhaustive, actionable plan for migrating ~90% of mc1710 (m7) game logic into `core/`, wired to `platform-api/` (PA) abstractions, with version-specific implementations remaining in each version submodule. + +--- + +## ⚠️ CRITICAL PERFORMANCE NOTE FOR AGENTS + +**HEAVILY PRIORITIZE `ast_grep_replace` AND `edit(replaceAll=true)` TOOLS — they are 100-1000x faster than individual read/edit cycles.** + +For bulk changes across multiple files: +- ❌ **NEVER** do individual `read()` + `edit()` per file +- ✅ **ALWAYS** use `ast_grep_replace()` for pattern-based bulk fixes across all files simultaneously +- ✅ **ALWAYS** use `edit(replaceAll=true)` for string replacements within a file (single call fixes ALL occurrences) + +**OPTIMIZED EXECUTION STRATEGY FOR EACH WAVE:** + +1. **Bulk Copy Phase**: Use SINGLE `cp` command to copy ALL files for the wave in one operation + ```bash + cp file1 dest1 && cp file2 dest2 && ... && cp fileN destN + ``` + +2. **Bulk Fix Phase**: Fire ast_grep_replace patterns in rapid succession to fix ALL files at once + - Each pattern = one concurrent batch fix affecting all copied files + - Fire 20+ patterns without waiting between them + +3. **Batch Create Phase**: If new PA interfaces are needed, create them in BATCH + - Don't create one interface per file + - Create all new interfaces ONCE in platform-api/ + - Then bulk-fix all files to import/use the new interfaces + +**Example FAST approach:** +```bash +# Instead of: read DialogController, edit, read Quest, edit, read Bank, edit (slow tool overhead) +# Do this: +# 1. cp DialogController Quest QuestCategory ... (single command, all files copied) +# 2. ast_grep_replace pattern="NBTTagCompound" rewrite="INbt" (affects all files at once) +# 3. ast_grep_replace pattern="EntityPlayer" rewrite="IPlayer" (affects all files at once) +# 4. Done in seconds vs. hours +``` + +Each ast_grep_replace pattern = one concurrent batch fix across potentially hundreds of files. This is the ONLY way to achieve acceptable speed for Wave 1-5 migrations. + +--- + +## How To Read This Document + +Each **Part** is an atomic migration unit that can be delegated to a single agent. Parts are grouped into **Waves** by dependency order. Within each Part: + +- **MOVE** = files moving from m7 to `core/` (retain same package) +- **ABSTRACT** = new PA interfaces needed (if not under `noppes.npcs.*`, put it in `common.minecraft.*` if it already doesn't exist). MUST NOT CREATE DUPLICATE INTERFACES, SO ALWAYS CHECK IF IT EXISTS +- **SHADOW** = m7 files that need mc1710-specific shadows after core move +- **VERIFY** = build commands to confirm success + +### PA Naming Rule +> When moving abstractions to PA: if the interface already exists under `noppes.npcs.api.*`, use it. If a NEW abstraction is needed and it doesn't belong under `noppes.npcs.*` or `common.minecraft.*`, create it under `common.minecraft.*`. + +### The Cycle (Every Part) +``` +1. CREATE any new PA interfaces needed +2. MOVE files to core/, replacing MC types with PA interfaces +3. CREATE m7 shadow files that add MC-specific behavior back +4. VERIFY: ./gradlew :core:compileJava && ./gradlew :mc1710:build +``` + +### MC Type → PA Replacement Quick Reference + +| MC Type | PA Replacement | Status | +|---------|---------------|--------| +| `NBTTagCompound` | `INbt` (`noppes.npcs.api`) | EXISTS | +| `NBTTagList` | `INbtList` (`noppes.npcs.api`) | EXISTS | +| `CompressedStreamTools` | `PlatformService.readCompressedNBT/writeCompressedNBT` | EXISTS | +| `EntityPlayer` / `EntityPlayerMP` | `IPlayer` (`noppes.npcs.api.entity`) | EXISTS | +| `Entity` | `IEntity` (`noppes.npcs.api.entity`) | EXISTS | +| `EntityLivingBase` | `IEntityLivingBase` (`noppes.npcs.api.entity`) | EXISTS | +| `ItemStack` | `IItemStack` (`noppes.npcs.api.item`) | EXISTS | +| `World` | `IWorld` (`noppes.npcs.api`) | EXISTS | +| `DamageSource` | `IDamageSource` (`noppes.npcs.api`) | EXISTS | +| `IInventory` | `IContainer` (`noppes.npcs.api`) | EXISTS | +| `MathHelper` | `ValueUtil` (`noppes.npcs.util`, in core) | EXISTS | +| `ChatComponentText` | `IMessageService` | **NEW — Wave 2** | +| `MinecraftServer` | `IServerService` | **NEW — Wave 2** | +| `StatCollector` | `ITranslationService` | **NEW — Wave 3** | +| `ForgeChunkManager` | N/A — STAYS in m7 | N/A | +| `EntityNPCInterface` | `ICustomNpc` (`noppes.npcs.api.entity`) | EXISTS | +| `SharedMonsterAttributes` | N/A — STAYS in m7 (entity-level) | N/A | +| `SideOnly/Side` | `@ClientOnly/@ServerOnly` (`kamkeel.npcs.platform.annotation`) | EXISTS | +| `IExtendedEntityProperties` | N/A — STAYS in m7 (Forge-specific) | N/A | +| `Forge Configuration` | `IConfigProvider` (`kamkeel.npcs.platform.config`) | EXISTS | +| `CustomNpcs.getWorldSaveDirectory()` | `PlatformService.getWorldSaveDirectory()` | EXISTS | + +--- + +## WAVE 0 — Foundation PA Interfaces (Prerequisite for everything) + +### Part 0.1: NBT JSON Utilities +> Move NBTJsonUtil to core with PA types. + +**MOVE to `core/`:** +| File | Package | MC Imports to Replace | +|------|---------|----------------------| +| `NBTJsonUtil.java` | `noppes.npcs.util` | `NBTTagCompound` → `INbt` | + +**ABSTRACT (new in PA):** +- Add `toJson(INbt)` / `fromJson(String)` methods to `noppes.npcs.platform.nbt.NBTIO` (already exists) + +**SHADOW in m7:** +- m7 `NBTJsonUtil` wraps core version, converts between `NBTTagCompound` and `INbt` + +**VERIFY:** `./gradlew :core:compileJava` + +--- + +### Part 0.2: Logging & String Utilities +> Move LogWriter and NoppesStringUtils to core. + +**MOVE to `core/`:** +| File | Package | MC Imports to Replace | +|------|---------|----------------------| +| `LogWriter.java` | `noppes.npcs` | Uses `PlatformService.logInfo/logWarn/logError` (already exists) | +| `NoppesStringUtils.java` | `noppes.npcs` | Pure logic — likely zero MC imports for string cleaning | + +**ABSTRACT:** None needed — `PlatformService` logging already exists. + +**SHADOW in m7:** m7 retains thin delegates if needed. + +**VERIFY:** `./gradlew :core:compileJava` + +--- + +### Part 0.3: Version Compatibility +> Move ICompatibilty and VersionCompatibility to core. + +**MOVE to `core/`:** +| File | Package | MC Imports to Replace | +|------|---------|----------------------| +| `ICompatibilty.java` | `noppes.npcs` | None (interface) | +| `VersionCompatibility.java` | `noppes.npcs` | `NBTTagCompound` → `INbt`. Static methods that upgrade old NBT formats. | + +**ABSTRACT:** None. + +**SHADOW in m7:** m7 shadow adds any MC-specific version compat logic. + +**VERIFY:** `./gradlew :core:compileJava` + +--- + +### Part 0.4: Action Framework (MC-FREE — Direct Move) +> 9 files, 0 MC imports. Pure game logic. + +**MOVE to `core/`:** +| File | Package | MC Imports | +|------|---------|------------| +| `Action.java` | `noppes.npcs.controllers.data.action` | 0 | +| `ActionChain.java` | `noppes.npcs.controllers.data.action.chain` | 0 | +| `ConditionalAction.java` | `noppes.npcs.controllers.data.action.action` | 0 | +| `ActionThread.java` | `noppes.npcs.controllers.data.action` | 0 | +| `ActionQueue.java` | `noppes.npcs.controllers.data.action` | 0 | +| `ActionManager.java` | `noppes.npcs.controllers.data.action` | 0 | +| `ActionLogger.java` | `noppes.npcs.controllers.data.action` | 0 | +| `ActionListener.java` | `noppes.npcs.controllers.data.action` | 0 | +| `ActionList.java` | `noppes.npcs.controllers.data.action` | 0 | + +**ABSTRACT:** None. +**SHADOW:** None. +**VERIFY:** `./gradlew :core:compileJava` + +--- + +### Part 0.5: Zero-MC Controllers (Direct Move) +> Controllers with 0 MC imports. + +**MOVE to `core/`:** +| File | Package | MC Imports | +|------|---------|------------| +| `CategoryManager.java` | `noppes.npcs.controllers` | 0 | +| `HookDefinition.java` | `noppes.npcs.controllers` | 0 | +| `ScriptHookController.java` | `noppes.npcs.controllers` | 0 | +| `APIRegistry.java` | `noppes.npcs.controllers` | 0 (already in core — verify) | + +**ABSTRACT:** None. +**SHADOW:** None. +**VERIFY:** `./gradlew :core:compileJava` + +--- + +## WAVE 1 — NBT-Only Controllers (Replace CompressedStreamTools + NBTTag*) + +These controllers use ONLY NBT types and `CustomNpcs.getWorldSaveDirectory()` — both already abstracted. + +### Part 1.1: DialogController + Dialog Data Classes +> Core dialog system. 4 files. + +**MOVE to `core/`:** +| File | Package | MC Imports to Replace | +|------|---------|----------------------| +| `DialogController.java` | `noppes.npcs.controllers` | `CompressedStreamTools` → `PlatformService`, `NBTTagCompound/List` → `INbt/INbtList` | +| `Dialog.java` | `noppes.npcs.controllers.data` | `NBTTagCompound/List` → `INbt/INbtList`, `EntityPlayer` → `IPlayer` (only in `hasDialogs()` and `copy()`) | +| `DialogCategory.java` | `noppes.npcs.controllers.data` | `NBTTagCompound/List` → `INbt/INbtList` | +| `DialogOption.java` | `noppes.npcs.controllers.data` | `NBTTagCompound` → `INbt`, `EntityPlayer` → `IPlayer` (in `isAvailable()`) | + +**Dependencies:** Part 0.1 (NBTJsonUtil), Part 0.2 (LogWriter, NoppesStringUtils), Availability (Part 1.5) + +**ABSTRACT:** None new — all types already in PA. + +**SHADOW in m7:** +- `DialogController.java` — shadow adds `SyncController` calls (networking, stays m7-side) +- `Dialog.java` — shadow adds `NBTWrapper` bridging for `DialogImage.writeToNBT` + +**VERIFY:** `./gradlew :core:compileJava && ./gradlew :mc1710:build` + +--- + +### Part 1.2: QuestController + Quest Data Classes +> Core quest system. 4 files. + +**MOVE to `core/`:** +| File | Package | MC Imports to Replace | +|------|---------|----------------------| +| `QuestController.java` | `noppes.npcs.controllers` | `CompressedStreamTools` → `PlatformService`, `NBTTagCompound/List` → `INbt/INbtList` | +| `Quest.java` | `noppes.npcs.controllers.data` | `NBTTagCompound` → `INbt`, `EntityPlayer` → `IPlayer` | +| `QuestCategory.java` | `noppes.npcs.controllers.data` | `NBTTagCompound/List` → `INbt/INbtList` | +| `QuestData.java` | `noppes.npcs.controllers.data` | `NBTTagCompound` → `INbt` | + +**Dependencies:** Part 0.1, Part 0.2, Availability (Part 1.5) + +**ABSTRACT:** None new. + +**SHADOW in m7:** +- `QuestController.java` — adds `SyncController` calls +- `Quest.java` — adds `EntityPlayer`-specific methods + +**VERIFY:** `./gradlew :core:compileJava && ./gradlew :mc1710:build` + +--- + +### Part 1.3: BankController + Bank Data +> Banking system. 3 files. + +**MOVE to `core/`:** +| File | Package | MC Imports to Replace | +|------|---------|----------------------| +| `BankController.java` | `noppes.npcs.controllers` | `CompressedStreamTools` → `PlatformService`, `NBTTagCompound/List` → `INbt/INbtList` | +| `Bank.java` | `noppes.npcs.controllers.data` | `NBTTagCompound` → `INbt` | +| `BankData.java` | `noppes.npcs.controllers.data` | `NBTTagCompound/List` → `INbt/INbtList`, `EntityPlayer` → `IPlayer`, `ItemStack` → `IItemStack`, `Container` → remove (m7 shadow) | + +**Dependencies:** Part 0.1, Part 0.2 + +**ABSTRACT:** None new. + +**SHADOW in m7:** +- `BankData.java` — shadow adds `Container` management, `EntityPlayerMP` packet sending + +**VERIFY:** `./gradlew :core:compileJava && ./gradlew :mc1710:build` + +--- + +### Part 1.4: AnimationController + Animation Data +> Animation system. 4 files. + +**MOVE to `core/`:** +| File | Package | MC Imports to Replace | +|------|---------|----------------------| +| `AnimationController.java` | `noppes.npcs.controllers` | `CompressedStreamTools` → `PlatformService`, `NBTTagCompound/List` → `INbt/INbtList` | +| `Animation.java` | `noppes.npcs.controllers.data` | `NBTTagCompound/List` → `INbt/INbtList` | +| `BuiltInAnimation.java` | `noppes.npcs.controllers.data` | `NBTTagCompound` → `INbt` | +| `AnimationData.java` | `noppes.npcs.controllers.data` | `NBTTagCompound` → `INbt`, `Entity/EntityLivingBase/EntityPlayer/EntityPlayerMP` → `IEntity/IPlayer`, `AxisAlignedBB` → remove (m7 shadow) | + +**Dependencies:** Part 0.1, Part 0.2 + +**ABSTRACT:** None new. + +**SHADOW in m7:** +- `AnimationData.java` — shadow adds MC entity interaction (position, AABB, player sync) + +**VERIFY:** `./gradlew :core:compileJava && ./gradlew :mc1710:build` + +--- + +### Part 1.5: Availability +> Cross-cutting availability checker. Used by Dialog, Quest, many others. + +**MOVE to `core/`:** +| File | Package | MC Imports to Replace | +|------|---------|----------------------| +| `Availability.java` | `noppes.npcs.controllers.data` | `EntityPlayer` → `IPlayer`, `NBTTagCompound` → `INbt`, `MathHelper` → `ValueUtil`, `StatCollector` → remove client method (m7 shadow), `SideOnly` → `@ClientOnly` | + +**Key insight:** `isAvailable(EntityPlayer)` checks world time, dialog/quest/faction progress, and XP level. Core version takes `IPlayer`. The `isAvailableText()` method is `@SideOnly(Side.CLIENT)` and uses `StatCollector` — this stays in m7 shadow only. + +**Dependencies:** Part 0.3 (ICompatibilty), FactionController (already in core), PlayerQuestController (Part 2.2), QuestController (Part 1.2) + +**ABSTRACT:** +- Add `getWorldTime()` to `IPlayer` or `IWorld` in PA (check if exists) +- Add `getExperienceLevel()` to `IPlayer` in PA (check if exists) + +**SHADOW in m7:** +- Adds `isAvailableText()` client-side method with `StatCollector` +- Adds `isAvailable(EntityPlayer)` bridge that wraps to `isAvailable(IPlayer)` + +**VERIFY:** `./gradlew :core:compileJava && ./gradlew :mc1710:build` + +--- + +### Part 1.6: LinkedItemController + LinkedItem Data +> Linked item template system. 2 files. + +**MOVE to `core/`:** +| File | Package | MC Imports to Replace | +|------|---------|----------------------| +| `LinkedItemController.java` | `noppes.npcs.controllers` | `CompressedStreamTools` → `PlatformService`, `NBTTagCompound/List` → `INbt/INbtList` | +| `LinkedItem.java` | `noppes.npcs.controllers.data` | `ItemStack` → `IItemStack`, `NBTTagCompound` → `INbt` | + +**Dependencies:** Part 0.1, Part 0.2 + +**ABSTRACT:** None new. + +**SHADOW in m7:** +- `LinkedItem.java` — shadow adds MC `ItemStack` field handling + +**VERIFY:** `./gradlew :core:compileJava && ./gradlew :mc1710:build` + +--- + +### Part 1.7: SpawnController + SpawnData +> Natural NPC spawning rules. 2 files. + +**MOVE to `core/`:** +| File | Package | MC Imports to Replace | +|------|---------|----------------------| +| `SpawnController.java` | `noppes.npcs.controllers` | `CompressedStreamTools` → `PlatformService`, `NBTTagCompound/List` → `INbt/INbtList`, `WeightedRandom` → inline or utility | +| `SpawnData.java` | `noppes.npcs.controllers.data` | `Entity/EntityList` → remove (m7 shadow), `NBTTagCompound` → `INbt`, `WeightedRandom.Item` → custom base class, `DimensionManager` → `PlatformService` | + +**ABSTRACT:** +- Add `getDimensionIds()` to `PlatformService` or create `common.minecraft.IServerService` + +**SHADOW in m7:** +- `SpawnData.java` — shadow adds `Entity` creation and `EntityList` lookups + +**VERIFY:** `./gradlew :core:compileJava && ./gradlew :mc1710:build` + +--- + +### Part 1.8: CustomEffectController + CustomEffect +> Custom status effects. 2 files. + +**MOVE to `core/`:** +| File | Package | MC Imports to Replace | +|------|---------|----------------------| +| `CustomEffectController.java` | `noppes.npcs.controllers` | `EntityPlayer` → `IPlayer`, `CompressedStreamTools` → `PlatformService`, `NBTTagCompound/List` → `INbt/INbtList` | +| `CustomEffect.java` | `noppes.npcs.controllers.data` | `EntityPlayer` → `IPlayer`, `NBTTagCompound` → `INbt` | + +**Dependencies:** Part 0.1, Part 0.2 + +**ABSTRACT:** None new. + +**SHADOW in m7:** +- `CustomEffectController.java` — shadow adds `EntityPlayer` UUID access, m7-specific effect application + +**VERIFY:** `./gradlew :core:compileJava && ./gradlew :mc1710:build` + +--- + +### Part 1.9: AuctionConfigSync + ScriptConfigSync + ProfileConfigSync +> Config sync utilities. 3 files. + +**MOVE to `core/`:** +| File | Package | MC Imports to Replace | +|------|---------|----------------------| +| `AuctionConfigSync.java` | `noppes.npcs.controllers` | `NBTTagCompound` → `INbt` | +| `ScriptConfigSync.java` | `noppes.npcs.controllers` | `NBTTagCompound` → `INbt` | +| `ProfileConfigSync.java` | `noppes.npcs.controllers` | `EntityPlayer` → `IPlayer`, `NBTTagCompound/List` → `INbt/INbtList` | + +**ABSTRACT:** None new. +**SHADOW:** None needed (or thin wrappers). +**VERIFY:** `./gradlew :core:compileJava && ./gradlew :mc1710:build` + +--- + +### Part 1.10: FactionOptions + DataTransform +> Small data classes. 2 files. + +**MOVE to `core/`:** +| File | Package | MC Imports to Replace | +|------|---------|----------------------| +| `FactionOptions.java` | `noppes.npcs.controllers.data` | `EntityPlayer` → `IPlayer`, `NBTTagCompound` → `INbt`, `ChatComponentTranslation` → remove (m7 shadow) | +| `DataTransform.java` | `noppes.npcs.controllers.data` | `NBTTagCompound` → `INbt` | + +**ABSTRACT:** None new. +**SHADOW in m7:** `FactionOptions.java` — shadow adds chat message sending. +**VERIFY:** `./gradlew :core:compileJava && ./gradlew :mc1710:build` + +--- + +## WAVE 2 — Player-Dependent Systems (Need IPlayer expansion + IMessageService) + +### Part 2.0: PA Interface Expansion +> Before Wave 2 work begins, expand PA. + +**NEW PA Interfaces:** +| Interface | Package | Methods | +|-----------|---------|---------| +| `IMessageService` | `common.minecraft` | `sendMessage(IPlayer, String)`, `sendTranslatedMessage(IPlayer, String, Object...)`, `broadcastMessage(String)` | +| `IServerService` | `common.minecraft` | `getOnlinePlayers()`, `getPlayerByName(String)`, `getPlayerByUUID(UUID)`, `isServerRunning()`, `getDimensionIds()` | + +**Expand existing `IPlayer`** (in `noppes.npcs.api.entity`): +- `getWorldTime()` (if not present) +- `getExperienceLevel()` (if not present) +- `getDialogsRead()` → `Set` (for Availability) +- `getPersistentID()` → `UUID` + +**Expand `PlatformService`:** +- `IMessageService messages()` +- `IServerService server()` + +**VERIFY:** `./gradlew :core:compileJava` + +--- + +### Part 2.1: Quest Type Implementations +> The actual quest logic. 6 files. + +**MOVE to `core/`:** +| File | Package | MC Imports to Replace | +|------|---------|----------------------| +| `QuestInterface.java` | `noppes.npcs.quests` | `EntityPlayer` → `IPlayer`, `NBTTagCompound` → `INbt` | +| `QuestDialog.java` | `noppes.npcs.quests` | `EntityPlayer` → `IPlayer`, `NBTTagCompound` → `INbt` | +| `QuestKill.java` | `noppes.npcs.quests` | `EntityPlayer` → `IPlayer`, `NBTTagCompound` → `INbt` | +| `QuestLocation.java` | `noppes.npcs.quests` | `EntityPlayer` → `IPlayer`, `NBTTagCompound` → `INbt`, `StatCollector` → `ITranslationService` or remove | +| `QuestManual.java` | `noppes.npcs.quests` | `EntityPlayer` → `IPlayer`, `NBTTagCompound` → `INbt` | +| `QuestItem.java` | `noppes.npcs.quests` | `EntityPlayer` → `IPlayer`, `ItemStack` → `IItemStack`, `NBTTagCompound` → `INbt` | + +**Key pattern:** `QuestInterface` is abstract with `isCompleted(PlayerData)`, `handleComplete(EntityPlayer)`, `getQuestLogStatus(EntityPlayer)`, `getObjectives(EntityPlayer)`. Core version changes `EntityPlayer` → `IPlayer` and `PlayerData` reference stays (PlayerData will also move to core in Wave 3). + +**Dependencies:** Part 1.2 (QuestController), Part 2.0 (PA expansion) + +**ABSTRACT:** +- `ITranslationService` in `common.minecraft` — `translate(String key)`, `translateFormatted(String key, Object... args)` — needed for `QuestLocation` + +**SHADOW in m7:** +- Each quest type may need shadow for `StatCollector` calls and inventory operations on raw `EntityPlayer` + +**VERIFY:** `./gradlew :core:compileJava && ./gradlew :mc1710:build` + +--- + +### Part 2.2: PlayerQuestController +> Quest progress tracking. 1 file. + +**MOVE to `core/`:** +| File | Package | MC Imports to Replace | +|------|---------|----------------------| +| `PlayerQuestController.java` | `noppes.npcs.controllers` | `EntityPlayer` → `IPlayer`, `EntityPlayerMP` → `IPlayer`, `ChatComponentTranslation` → `IMessageService` | + +**Dependencies:** Part 2.0 (IMessageService), Part 1.2 (QuestController) + +**ABSTRACT:** None new (IMessageService from Part 2.0). + +**SHADOW in m7:** Shadow adds MC-specific chat formatting. + +**VERIFY:** `./gradlew :core:compileJava && ./gradlew :mc1710:build` + +--- + +### Part 2.3: PartyController + Party +> Player grouping. 2 files. + +**MOVE to `core/`:** +| File | Package | MC Imports to Replace | +|------|---------|----------------------| +| `PartyController.java` | `noppes.npcs.controllers` | `EntityPlayer/EntityPlayerMP` → `IPlayer`, `NBTTagCompound/List/String` → `INbt/INbtList`, `ChatComponentTranslation` → `IMessageService` | +| `Party.java` | `noppes.npcs.controllers.data` | `EntityPlayer/EntityPlayerMP` → `IPlayer`, `NBTTagCompound/List` → `INbt/INbtList`, `ChatComponentText` → `IMessageService` | + +**Dependencies:** Part 2.0 (IMessageService, IServerService) + +**ABSTRACT:** None new. + +**SHADOW in m7:** Shadows add MC player lookups and chat message construction. + +**VERIFY:** `./gradlew :core:compileJava && ./gradlew :mc1710:build` + +--- + +### Part 2.4: AuctionController + Auction Data +> Auction/economy system. 4 files. + +**MOVE to `core/`:** +| File | Package | MC Imports to Replace | +|------|---------|----------------------| +| `AuctionController.java` | `noppes.npcs.controllers` | `EntityPlayer/EntityPlayerMP` → `IPlayer`, `ItemStack` → `IItemStack`, `CompressedStreamTools` → `PlatformService`, `NBTTagCompound/List` → `INbt/INbtList`, `ChatComponentText/EnumChatFormatting` → `IMessageService` | +| `AuctionListing.java` | `noppes.npcs.controllers.data` | `ItemStack` → `IItemStack`, `NBTTagCompound` → `INbt` | +| `AuctionClaim.java` | `noppes.npcs.controllers.data` | `ItemStack` → `IItemStack`, `NBTTagCompound` → `INbt` | +| `AuctionBlacklist.java` | `noppes.npcs.controllers.data` | `EntityPlayer` → `IPlayer`, `ItemStack` → `IItemStack`, `NBTTagCompound` → `INbt` | + +**Dependencies:** Part 2.0 (IMessageService), Part 0.1 (NBTJsonUtil) + +**ABSTRACT:** None new. + +**SHADOW in m7:** `AuctionController` shadow adds SyncController calls, packet sending. + +**VERIFY:** `./gradlew :core:compileJava && ./gradlew :mc1710:build` + +--- + +### Part 2.5: MarketRegistry +> Currency and trader integration. 1 file. + +**MOVE to `core/`:** +| File | Package | MC Imports to Replace | +|------|---------|----------------------| +| `MarketRegistry.java` | `noppes.npcs.controllers` | `EntityPlayerMP` → `IPlayer`, `NBTTagCompound` → `INbt` | + +**Dependencies:** Part 2.0 + +**ABSTRACT:** None new. +**SHADOW in m7:** Adds packet sending. +**VERIFY:** `./gradlew :core:compileJava && ./gradlew :mc1710:build` + +--- + +### Part 2.6: AttributeController +> Player attribute definitions. 1 file. + +**MOVE to `core/`:** +| File | Package | MC Imports to Replace | +|------|---------|----------------------| +| `AttributeController.java` | `kamkeel.npcs.controllers` | `EntityPlayer` → `IPlayer` | + +**Dependencies:** Part 2.0 + +**ABSTRACT:** None new. +**SHADOW:** None needed. +**VERIFY:** `./gradlew :core:compileJava && ./gradlew :mc1710:build` + +--- + +### Part 2.7: ProfileController +> Multi-character profiles. 1 file. + +**MOVE to `core/`:** +| File | Package | MC Imports to Replace | +|------|---------|----------------------| +| `ProfileController.java` | `kamkeel.npcs.controllers` | `EntityPlayer/EntityPlayerMP` → `IPlayer`, `CompressedStreamTools` → `PlatformService`, `NBTTagCompound` → `INbt` | + +**Dependencies:** Part 2.0 (IServerService for player lookups) + +**ABSTRACT:** None new. + +**SHADOW in m7:** Adds `EntityPlayerMP`-specific packet operations. + +**VERIFY:** `./gradlew :core:compileJava && ./gradlew :mc1710:build` + +--- + +### Part 2.8: ServerCloneController + ServerTagMapController +> Clone tab and tag map management. 2 files. + +**MOVE to `core/`:** +| File | Package | MC Imports to Replace | +|------|---------|----------------------| +| `ServerTagMapController.java` | `noppes.npcs.controllers` | `CompressedStreamTools` → `PlatformService`, `NBTTagCompound` → `INbt` | + +**SPLITTABLE (clone controller uses Entity/EntityList):** +| File | Package | MC Imports to Replace | +|------|---------|----------------------| +| `ServerCloneController.java` | `noppes.npcs.controllers` | Core: file/NBT management moves. Shadow: `Entity`, `EntityList`, `ICommandSender`, `ChatComponentText` stay. | + +**Dependencies:** Part 0.1 (NBTJsonUtil), Part 2.0 (IMessageService) + +**ABSTRACT:** None new. + +**SHADOW in m7:** `ServerCloneController` shadow adds entity spawning from NBT. + +**VERIFY:** `./gradlew :core:compileJava && ./gradlew :mc1710:build` + +--- + +## WAVE 3 — Player Data System (Central, Many Dependencies) + +### Part 3.0: Player Sub-Data Classes (NBT-only) +> Player data components that only use NBT. 6 files. + +**MOVE to `core/`:** +| File | Package | MC Imports to Replace | +|------|---------|----------------------| +| `PlayerBankData.java` | `noppes.npcs.controllers.data` | `NBTTagCompound/List` → `INbt/INbtList` | +| `PlayerItemGiverData.java` | `noppes.npcs.controllers.data` | `NBTTagCompound` → `INbt` | +| `PlayerMailData.java` | `noppes.npcs.controllers.data` | `NBTTagCompound/List` → `INbt/INbtList` | +| `PlayerTradeData.java` | `noppes.npcs.controllers.data` | `NBTTagCompound/List` → `INbt/INbtList` | + +**Dependencies:** Part 1.3 (Bank) + +**ABSTRACT:** None new. +**SHADOW:** Thin m7 wrappers if any MC bridge needed. +**VERIFY:** `./gradlew :core:compileJava && ./gradlew :mc1710:build` + +--- + +### Part 3.1: PlayerFactionData + PlayerQuestData +> Player progress tracking. 2 files with EntityPlayer usage. + +**MOVE to `core/`:** +| File | Package | MC Imports to Replace | +|------|---------|----------------------| +| `PlayerFactionData.java` | `noppes.npcs.controllers.data` | `EntityPlayer/EntityPlayerMP` → `IPlayer`, `NBTTagCompound/List` → `INbt/INbtList` | +| `PlayerQuestData.java` | `noppes.npcs.controllers.data` | `EntityPlayer/EntityPlayerMP` → `IPlayer`, `NBTTagCompound/List` → `INbt/INbtList` | + +**Dependencies:** Part 2.0, Part 2.2 + +**ABSTRACT:** None new. + +**SHADOW in m7:** Shadows add `EntityPlayerMP` packet sending for sync. + +**VERIFY:** `./gradlew :core:compileJava && ./gradlew :mc1710:build` + +--- + +### Part 3.2: PlayerMail +> Mail system. 1 file — heavier MC coupling. + +**MOVE to `core/`:** +| File | Package | MC Imports to Replace | +|------|---------|----------------------| +| `PlayerMail.java` | `noppes.npcs.controllers.data` | `EntityPlayer` → `IPlayer`, `IInventory` → `IContainer`, `ItemStack` → `IItemStack`, `NBTTagCompound/List/String` → `INbt/INbtList` | + +**Dependencies:** Part 2.0 + +**ABSTRACT:** None new (IContainer exists). + +**SHADOW in m7:** Shadow adds MC inventory implementation. + +**VERIFY:** `./gradlew :core:compileJava && ./gradlew :mc1710:build` + +--- + +### Part 3.3: PlayerAbilityData + PlayerAbilityHotbarData +> Ability system player data. 2 files — medium MC coupling. + +**MOVE to `core/`:** +| File | Package | MC Imports to Replace | +|------|---------|----------------------| +| `PlayerAbilityHotbarData.java` | `noppes.npcs.controllers.data` | `EntityPlayer/EntityPlayerMP` → `IPlayer`, `NBTTagCompound` → `INbt` | + +**SPLITTABLE:** +| File | Package | Notes | +|------|---------|-------| +| `PlayerAbilityData.java` | `noppes.npcs.controllers.data` | 7 MC imports including `EntityLivingBase`, `DamageSource`. Core version holds data/state. Shadow adds combat methods. | + +**Dependencies:** Part 2.0, AbilityController (already in core) + +**ABSTRACT:** None new. + +**SHADOW in m7:** `PlayerAbilityData` shadow adds damage processing, entity targeting. + +**VERIFY:** `./gradlew :core:compileJava && ./gradlew :mc1710:build` + +--- + +### Part 3.4: PlayerDataController +> Central player data management. 1 file — heavy MC coupling. + +**SPLITTABLE:** +| File | Package | MC Imports | +|------|---------|------------| +| `PlayerDataController.java` | `noppes.npcs.controllers` | 9 MC imports: `ICommandSender`, `PlayerSelector`, `EntityPlayer`, `EntityPlayerMP`, `CompressedStreamTools`, `NBTTagCompound`, `NBTTagList`, `MinecraftServer`, `ChatComponentText` | + +**Core version:** Data persistence logic (load/save/cache), player map management. +**Shadow:** MC-specific player lookup (`PlayerSelector`), `MinecraftServer` access, command sender operations. + +**Dependencies:** Part 2.0, Part 3.0-3.3 + +**ABSTRACT:** Uses `IServerService` from Part 2.0. + +**VERIFY:** `./gradlew :core:compileJava && ./gradlew :mc1710:build` + +--- + +### Part 3.5: PlayerData (THE BIG ONE) +> Central player data aggregator. 1 file — heaviest MC coupling of any data class. + +**SPLITTABLE — Core version holds:** +- All sub-data instances (dialogData, bankData, questData, etc.) +- `setNBT()` / `getNBT()` logic using `INbt` +- `playername`, `uuid` fields +- `save()` logic (using `PlatformService`) +- Party invite management (pure game logic) + +**Shadow adds:** +- `implements IExtendedEntityProperties` (Forge-specific) +- `EntityPlayer player` field → raw MC player reference +- `EntityNPCInterface editingNpc`, `activeCompanion` fields +- `setCompanion()`, `updateCompanion()` methods (entity-level) +- `get(EntityPlayer)` static factory method +- `onLogin()` / `onLogout()` MC-specific lifecycle +- `DBCAddon` integration + +**Dependencies:** All of Wave 3, Part 2.0 + +**ABSTRACT:** None new — uses `IPlayer`, `INbt`, `PlatformService`. + +**VERIFY:** `./gradlew :core:compileJava && ./gradlew :mc1710:build` + +--- + +## WAVE 4 — Config System + +### Part 4.1: Config Data Classes (Values Only) +> Extract pure config values to core. 9+ files. + +**Pattern:** Each config file has two parts: +1. **Values** (static fields like `NpcNavRange`, `EnableUpdateChecker`) — move to `core/` +2. **Forge loading** (uses `Configuration`, `Property`) — stays in m7 + +**MOVE to `core/` (new files):** +Create `CoreConfig*.java` classes in `noppes.npcs.config` that hold ONLY the static value fields. + +| New Core File | Extracts Values From | +|--------------|---------------------| +| `CoreConfigMain.java` | `ConfigMain.java` | +| `CoreConfigMarket.java` | `ConfigMarket.java` | +| `CoreConfigEnergy.java` | `ConfigEnergy.java` | +| `CoreConfigItem.java` | `ConfigItem.java` | +| `CoreConfigDebug.java` | `ConfigDebug.java` | +| `CoreConfigExperimental.java` | `ConfigExperimental.java` | +| `CoreConfigScript.java` | `ConfigScript.java` | + +**m7 versions:** Keep Forge `Configuration` loading, write values into the core config classes. + +**Already exists:** `CoreConfig.java` in core — extend this pattern. + +**MOVE to `core/`:** +| File | Package | MC Imports | +|------|---------|------------| +| `LoadConfiguration.java` | `noppes.npcs.config` | 0 — pure coordination | +| `legacy/ConfigProp.java` | `noppes.npcs.config.legacy` | 0 — pure annotation | +| `legacy/LegacyLoader.java` | `noppes.npcs.config.legacy` | 0 — pure file parsing | + +**STAYS in m7:** +- `GlyphCache.java` — OpenGL rendering +- `StringCache.java` — MC Tessellator rendering +- `legacy/LegacyConfig.java` — uses `Minecraft`, `MinecraftServer` for paths +- `ConfigClient.java` — client-specific, uses `Minecraft` +- `ConfigMixin.java` — mixin-specific + +**VERIFY:** `./gradlew :core:compileJava && ./gradlew :mc1710:build` + +--- + +## WAVE 5 — Roles & Jobs System + +### Part 5.0: Role/Job Base Interfaces +> The abstract base classes. 2 files. + +**MOVE to `core/`:** +| File | Package | MC Imports to Replace | +|------|---------|----------------------| +| `RoleInterface.java` | `noppes.npcs.roles` | `EntityPlayer` → `IPlayer`, `NBTTagCompound` → `INbt`. Constructor: `EntityNPCInterface` → `ICustomNpc` | +| `JobInterface.java` | `noppes.npcs.roles` | `ItemStack` → `IItemStack`, `NBTTagCompound` → `INbt`. Constructor: `EntityNPCInterface` → `ICustomNpc` | + +**Key decision:** The `npc` field changes from `EntityNPCInterface` to `ICustomNpc`. This is the single most impactful change — every role/job subclass uses `this.npc`. + +**Dependencies:** Part 2.0 + +**ABSTRACT:** `ICustomNpc` already exists in PA. May need method additions for: +- `getWorldTime()`, `getPosition()`, `isAlive()`, `isDead()` + +**SHADOW in m7:** Both get shadows that cast `ICustomNpc` back to `EntityNPCInterface` for MC-specific method access. + +**VERIFY:** `./gradlew :core:compileJava && ./gradlew :mc1710:build` + +--- + +### Part 5.1: Simple Roles (Low MC Coupling) +> Roles with 2-3 MC imports, mostly EntityPlayer. + +**MOVE to `core/`:** +| File | Package | MC Imports to Replace | +|------|---------|----------------------| +| `RoleBank.java` | `noppes.npcs.roles` | `EntityPlayer` → `IPlayer`, `NBTTagCompound` → `INbt` | +| `RoleAuctioneer.java` | `noppes.npcs.roles` | `EntityPlayer` → `IPlayer`, `NBTTagCompound` → `INbt` | +| `RoleMount.java` | `noppes.npcs.roles` | `EntityPlayer` → `IPlayer`, `NBTTagCompound` → `INbt` | +| `RoleTransporter.java` | `noppes.npcs.roles` | `EntityPlayer` → `IPlayer`, `NBTTagCompound` → `INbt`, `ChatComponentTranslation` → `IMessageService` | +| `RolePostman.java` | `noppes.npcs.roles` | `EntityPlayer` → `IPlayer`, `NBTTagCompound` → `INbt`, `ChatComponentTranslation` → `IMessageService` | + +**Dependencies:** Part 5.0, Part 2.0 + +**ABSTRACT:** None new. + +**SHADOW in m7:** Shadows add `interact()` MC-specific GUI opening. + +**VERIFY:** `./gradlew :core:compileJava && ./gradlew :mc1710:build` + +--- + +### Part 5.2: Medium Roles +> Roles with more MC coupling. + +**MOVE to `core/`:** +| File | Package | MC Imports to Replace | +|------|---------|----------------------| +| `RoleFollower.java` | `noppes.npcs.roles` | `EntityPlayer` → `IPlayer`, `NBTTagCompound` → `INbt`, `ChatComponentTranslation/StatCollector` → `IMessageService`/`ITranslationService` | +| `RoleInnkeeper.java` | `noppes.npcs.roles` | `EntityPlayer` → `IPlayer`, `NBTBase/NBTTagCompound/List` → `INbt/INbtList`, `ChatComponentTranslation` → `IMessageService` | +| `RoleTrader.java` | `noppes.npcs.roles` | `EntityPlayer/EntityPlayerMP` → `IPlayer`, `ItemStack` → `IItemStack`, `NBTTagCompound/List` → `INbt/INbtList` | + +**Dependencies:** Part 5.0, Part 2.0, Part 2.5 (MarketRegistry) + +**ABSTRACT:** None new. + +**SHADOW in m7:** Shadows add trader stock ItemStack operations, GUI packet sending. + +**VERIFY:** `./gradlew :core:compileJava && ./gradlew :mc1710:build` + +--- + +### Part 5.3: Simple Jobs +> Jobs with low MC coupling. + +**MOVE to `core/`:** +| File | Package | MC Imports to Replace | +|------|---------|----------------------| +| `JobFollower.java` | `noppes.npcs.roles` | `NBTTagCompound` → `INbt` (1 MC import — MOVABLE) | +| `JobConversation.java` | `noppes.npcs.roles` | `EntityPlayer` → `IPlayer`, `NBTTagCompound/List` → `INbt/INbtList` | +| `JobHealer.java` | `noppes.npcs.roles` | `EntityLivingBase` → `IEntityLivingBase`, `EntityPlayer` → `IPlayer`, `NBTTagCompound` → `INbt` | +| `JobItemGiver.java` | `noppes.npcs.roles` | `EntityPlayer` → `IPlayer`, `Item/ItemStack` → `IItemStack`, `NBTTagCompound/List` → `INbt/INbtList` | + +**Dependencies:** Part 5.0, Part 2.0 + +**ABSTRACT:** None new. + +**SHADOW in m7:** Shadows add MC item giving, entity healing. + +**VERIFY:** `./gradlew :core:compileJava && ./gradlew :mc1710:build` + +--- + +### Part 5.4: Complex Jobs +> Jobs with heavier MC coupling. + +**SPLITTABLE:** +| File | Package | Notes | +|------|---------|-------| +| `JobGuard.java` | `noppes.npcs.roles` | Core: targeting config, NBT. Shadow: `EntityList`, `IMob`, `EntityDragon`, etc. | +| `JobBard.java` | `noppes.npcs.roles` | Core: music config, NBT. Shadow: `Minecraft` client music, `ItemStack` | + +**STAYS in m7:** +| File | Package | Reason | +|------|---------|--------| +| `JobSpawner.java` | `noppes.npcs.roles` | 6 MC entity imports, spawns entities directly | +| `JobChunkLoader.java` | `noppes.npcs.roles` | `ForgeChunkManager` — deeply Forge-specific | + +**Dependencies:** Part 5.0, Part 2.0 + +**VERIFY:** `./gradlew :core:compileJava && ./gradlew :mc1710:build` + +--- + +### Part 5.5: Companion System +> RoleCompanion + companion jobs. 6 files. + +**STAYS in m7 (too MC-coupled):** +| File | Package | MC Imports | Reason | +|------|---------|------------|--------| +| `RoleCompanion.java` | `noppes.npcs.roles` | 18 | Items, armor, attributes, damage, food, Vec3 | +| `CompanionFoodStats.java` | `noppes.npcs.roles.companion` | 5 | `ItemFood`, `DamageSource`, `EnumDifficulty` | +| `CompanionGuard.java` | `noppes.npcs.roles.companion` | 5 | `Entity`, `IMob`, `EntityCreeper` | + +**MOVE to `core/`:** +| File | Package | MC Imports to Replace | +|------|---------|----------------------| +| `CompanionJobInterface.java` | `noppes.npcs.roles.companion` | `NBTTagCompound` → `INbt` | +| `CompanionFarmer.java` | `noppes.npcs.roles.companion` | `NBTTagCompound` → `INbt` (MOVABLE — 1 MC import) | +| `CompanionTrader.java` | `noppes.npcs.roles.companion` | `EntityPlayer` → `IPlayer`, `NBTTagCompound` → `INbt` | + +**Dependencies:** Part 5.0 + +**VERIFY:** `./gradlew :core:compileJava && ./gradlew :mc1710:build` + +--- + +## WAVE 6 — Script System (Partial Migration) + +### Part 6.1: ScriptContainer +> Individual script execution context. + +**MOVE to `core/`:** +| File | Package | MC Imports to Replace | +|------|---------|----------------------| +| `ScriptContainer.java` | `noppes.npcs.controllers` | `NBTTagCompound` → `INbt` (1 MC import — MOVABLE) | + +**Dependencies:** None. +**VERIFY:** `./gradlew :core:compileJava && ./gradlew :mc1710:build` + +--- + +### Part 6.2: Script Data Classes (NBT-only) +> Script handler data that only uses NBT. + +**MOVE to `core/`:** +| File | Package | MC Imports to Replace | +|------|---------|----------------------| +| `AbilityScript.java` | `noppes.npcs.controllers.data` | `NBTTagCompound` → `INbt` | +| `EffectScript.java` | `noppes.npcs.controllers.data` | `NBTTagCompound` → `INbt` | +| `LinkedItemScript.java` | `noppes.npcs.controllers.data` | `NBTTagCompound` → `INbt` | +| `RecipeScript.java` | `noppes.npcs.controllers.data` | `NBTTagCompound` → `INbt` | +| `ChainedAbilityScript.java` | `noppes.npcs.controllers.data` | `NBTTagCompound` → `INbt` | +| `IScriptHandlerPacket.java` | `noppes.npcs.controllers.data` | `NBTTagCompound` → `INbt` | +| `IScriptUnit.java` | `noppes.npcs.controllers.data` | `NBTTagCompound` → `INbt` | + +**STAYS in m7 (too MC-coupled or Forge-specific):** +| File | Reason | +|------|--------| +| `ScriptHandler.java` | Extends script engine internals | +| `SingleScriptHandler.java` | Forge `Constants` usage | +| `MultiScriptHandler.java` | `NBTTagCompound` deep integration | +| `DataScript.java` | `Entity`, `World`, `WorldServer` | +| `PlayerDataScript.java` | `EntityPlayer`, `BlockPos` | +| `ForgeDataScript.java` | 7 Forge event imports | +| `GlobalNPCDataScript.java` | `NBTTagCompound`, `BlockPos` | +| `JaninoScriptHandler.java` | `NBTTagCompound` | +| `IScriptHandler.java` | Deep scripting contract | +| `IScriptBlockHandler.java` | Block-level scripting | +| `INpcScriptHandler.java` | NPC-level scripting | +| `ScriptController.java` | 7 MC imports, `MinecraftServer` | +| `ScriptEntityData.java` | `IExtendedEntityProperties` | + +**VERIFY:** `./gradlew :core:compileJava && ./gradlew :mc1710:build` + +--- + +## WAVE 7 — SyncController (Networking Bridge) + +### Part 7.1: SyncController Core Logic +> The sync system is heavily MC-coupled but its DATA preparation logic can be extracted. + +**SPLITTABLE:** +| File | Package | Notes | +|------|---------|-------| +| `SyncController.java` | `kamkeel.npcs.controllers` | Core: sync revision tracking, data preparation methods (`updateDialogCat`, `updateQuestCat`, etc.). Shadow: `Minecraft`, `EntityPlayerMP`, `MinecraftServer`, packet sending. | + +**ABSTRACT:** +- Add `ISyncService` to `common.minecraft` — `syncUpdate(EnumSyncType, int, INbt)`, `syncRemove(EnumSyncType, int)` + +**Dependencies:** All of Waves 1-3 (controllers that call SyncController) + +**VERIFY:** `./gradlew :core:compileJava && ./gradlew :mc1710:build` + +--- + +## WAVE 8 — NPC Data Classes (Entity-Coupled, SPLIT ONLY) + +> These are the hardest. Each stores an `EntityNPCInterface` field and calls MC methods extensively. + +### Part 8.1: DataAdvanced +> NPC lines, sounds, factions, roles, jobs. + +**SPLITTABLE:** +- Core: All serializable fields (faction ID, lines, sounds config), `readNBT`/`writeNBT` using `INbt` +- Shadow: `EntityNPCInterface` reference, role/job instance creation, MC-specific setters + +### Part 8.2: DataStats +> Combat stats, resistances, attributes. + +**SPLITTABLE:** +- Core: All stat fields (HP, damage, armor, resistances), NBT serialization +- Shadow: `SharedMonsterAttributes` application, `EnumCreatureAttribute` + +### Part 8.3: DataAI +> Movement, combat tactics, pathfinding config. + +**SPLITTABLE:** +- Core: All AI config fields (nav type, combat policy, speeds, ranges), NBT serialization +- Shadow: `SharedMonsterAttributes` application, `MathHelper`, position access + +### Part 8.4: DataDisplay +> Skin, model, overlays, visual settings. + +**SPLITTABLE:** +- Core: All display fields (skin URL, model type, overlays, name, tint), NBT serialization +- Shadow: `Minecraft` client texture loading, `EntityPlayer` skin resolution, `NBTUtil`, `MinecraftServer` profile lookups + +### Part 8.5: DataAbilities +> Ability slots, cooldowns, execution phases. + +**SPLITTABLE:** +- Core: Ability slot data, cooldown timers, NBT serialization +- Shadow: `Entity/EntityLivingBase` targeting, `DamageSource`, world time access + +### Part 8.6: DataInventory +> Equipment, drops, loot. Implements `IInventory`. + +**STAYS in m7:** +- 11 MC imports, `implements IInventory`, direct `ItemStack` field management, `EntityItem` spawning +- Too deeply coupled to MC inventory system to split cleanly + +--- + +## STAYS IN M7 — Files That Do NOT Move + +These files are deeply MC-coupled and stay version-specific. Listed for completeness. + +### Controllers +| File | Reason | +|------|--------| +| `ChunkController.java` | `ForgeChunkManager`, `LoadingCallback` — Forge-specific | +| `CustomGuiController.java` | GUI packets, `EntityPlayerMP` networking | +| `LinkedNpcController.java` | `EntityNPCInterface`, `EntityCustomNpc` entity operations | +| `RecipeController.java` | `InventoryCrafting`, `CraftingManager`, `ItemStack` — extends MC recipe system | +| `EnergyController.java` | `Entity`, `EntityLivingBase`, `World` — spawns energy entities | +| `TelegraphController.java` | `Entity`, `EntityPlayerMP`, `World` — visual effects | +| `ScriptController.java` | `MinecraftServer`, `WorldEvent`, player commands | +| `ScriptEntityData.java` | `IExtendedEntityProperties` — Forge-specific | + +### Data Classes +| File | Reason | +|------|--------| +| `RecipeCarpentry.java` | `extends ShapedRecipes` — MC recipe class | +| `RecipeAnvil.java` | `ItemStack`, Forge `Constants` | +| `RecipesDefault.java` | `Block`, `Items`, `Item`, `ItemStack` — MC block/item references | +| `MarkData.java` | `IExtendedEntityProperties`, `Entity`, `World` | +| `DataInventory.java` | `implements IInventory`, 11 MC imports | + +### Roles +| File | Reason | +|------|--------| +| `RoleCompanion.java` | 18 MC imports — items, armor, attributes, damage | +| `JobSpawner.java` | Entity spawning | +| `JobChunkLoader.java` | `ForgeChunkManager` | +| `JobBard.java` (partial) | `Minecraft` client audio | +| `CompanionFoodStats.java` | `ItemFood`, `DamageSource` | +| `CompanionGuard.java` | `Entity`, `IMob` | + +### Entire Subsystems (per-version, no core equivalent) +| Subsystem | Files | Reason | +|-----------|-------|--------| +| `noppes.npcs.entity/` | 40 | Extend MC Entity classes | +| `noppes.npcs.blocks/` + `tiles/` | 98 | Extend MC Block/TileEntity | +| `noppes.npcs.items/` | 56 | Extend MC Item | +| `noppes.npcs.ai/` | 42 | Extend MC EntityAIBase | +| `noppes.npcs.client/` + `kamkeel.npcs.client/` | 642 | MC rendering | +| `kamkeel.npcs.network/` | 296 | MC networking | +| `kamkeel.npcs.command/` | 33 | MC command system | +| `noppes.npcs.scripted/` | 109 | MC wrapper classes | +| `noppes.npcs.containers/` | ~30 | Extend MC Container | +| `noppes.npcs.mixin/` | ~8 | Per-version mixins | +| `kamkeel.npcs.addon/` | ~5 | Per-version addons | +| `noppes.npcs.enchants/` | ~5 | Extend MC Enchantment | +| `noppes.npcs.compat/` | ~5 | Per-version compatibility | + +--- + +## Summary Statistics + +| Category | Files to Core | Files Staying | New PA Interfaces | +|----------|--------------|---------------|-------------------| +| **Wave 0** (Foundation) | ~18 | 0 | 0 | +| **Wave 1** (NBT-only) | ~25 | 0 | ~2 methods on IPlayer/IWorld | +| **Wave 2** (Player-dependent) | ~20 | 0 | `IMessageService`, `IServerService`, `ITranslationService` | +| **Wave 3** (PlayerData) | ~12 | 0 | 0 | +| **Wave 4** (Config) | ~10 | 5 | 0 | +| **Wave 5** (Roles/Jobs) | ~18 | 6 | 0 | +| **Wave 6** (Scripts) | ~8 | 13 | 0 | +| **Wave 7** (Sync) | 1 (split) | 0 | `ISyncService` | +| **Wave 8** (NPC Data) | 5 (split) | 1 | 0 | +| **TOTAL** | **~117 files** | **~1,370+** | **4 new interfaces** | + +### After full migration: +- **core/**: ~305 files (188 current + 117 new) +- **m7-only**: ~1,370 files (entity, blocks, items, AI, client, networking, commands, scripting wrappers) +- **Code sharing ceiling**: ~18% of total codebase in core — but this covers ~90% of GAME LOGIC (controllers, data, quest logic, roles, config values) + +--- + +## Execution Order + +``` +Wave 0 ████ (Parts 0.1-0.5) — No dependencies, do first +Wave 1 ████████ (Parts 1.1-1.10) — Depends on Wave 0 +Wave 2 ██████ (Parts 2.0-2.8) — Depends on Wave 1 (esp. Availability) +Wave 3 ████████ (Parts 3.0-3.5) — Depends on Wave 2 +Wave 4 ████ (Part 4.1) — Independent of Waves 2-3, can parallel +Wave 5 ████████ (Parts 5.0-5.5) — Depends on Wave 2 (IMessageService) +Wave 6 ████ (Parts 6.1-6.2) — Independent, can parallel with Wave 3+ +Wave 7 ██ (Part 7.1) — Depends on Waves 1-3 +Wave 8 ██████ (Parts 8.1-8.6) — Last, most complex splits +``` + +**Parallelizable:** +- Wave 0 → then Wave 1 +- Waves 4, 6 can run in parallel with Waves 2-3 +- Wave 5 can start after Part 2.0 + +--- + +## Agent Delegation Guide + +Each Part is designed to be delegated to a single `unspecified-high` agent with: +1. This document as context +2. SESSION_MEMORY.md for architecture understanding +3. Clear success criteria: `./gradlew :core:compileJava && ./gradlew :mc1710:build` + +**Per-Part agent prompt template:** +``` +Execute Part X.Y of the CORE_MIGRATION_PLAN. +- Read the Part description for exact files and changes +- Follow the MOVE → ABSTRACT → SHADOW → VERIFY cycle +- Use INbt instead of NBTTagCompound, IPlayer instead of EntityPlayer, etc. +- Retain same package when moving to core/ +- New PA interfaces go under common.minecraft if not under noppes.npcs.api +- Run ./gradlew :core:compileJava && ./gradlew :mc1710:build to verify +- Create .AGENTS/PART_X_Y_REPORT.md upon completion +``` diff --git a/.AGENTS/MIGRATION_PLAN.md b/.AGENTS/MIGRATION_PLAN.md new file mode 100644 index 000000000..788df6549 --- /dev/null +++ b/.AGENTS/MIGRATION_PLAN.md @@ -0,0 +1,1283 @@ +# MIGRATION PLAN — m7 → core/ (Phase 1A: Core Expansion) + +**Created:** 2026-03-15 +**Purpose:** Exhaustive, mechanically-executable plan for migrating game logic from mc1710 (m7) into core/. +**Consumed by:** Sisyphus (orchestrator) executing directly + verification by humans. + +--- + +## 🚀 EXECUTION STRATEGY (UPDATED 2026-03-15) + +### Why Direct Orchestrator Execution (NOT Agent Delegation) + +**Sisyphus will execute all Parts directly.** Here's why this is CRITICAL: + +| Factor | Agents | Direct Execution | +|--------|--------|------------------| +| **Speed** | ~8+ hours (spawn overhead, context-switching, slow edits) | ~2-3 hours (no overhead, bulk edits) | +| **Edit Quality** | Multiple passes per file, each touching code → bloats diffs, loses formatting | Single surgical read → one bulk edit per file → preserves ALL formatting | +| **File Handling** | Edit 1 file at a time, multiple edits per file | Read 5-10 files in parallel, bulk-edit each once | +| **Git Hygiene** | Many small commits, reformatted files → large bloated diffs | Minimal diffs, one commit per Part (human commits after build verification) | +| **Context** | Loses full context between calls, must re-explain | Maintains full session context, understands all tradeoffs | + +### 🔴 CRITICAL EXECUTION RULES (UPDATED 2026-03-15) + +**MANDATORY — NO EXCEPTIONS:** + +1. **Parallel Bulk Edits (VITAL)** + - For EACH Part: Read ALL files for that Part in parallel + - Edit ALL files in ONE response using parallel `edit()` calls + - Each file gets ONE edit() call with ALL its required changes (imports + types + everything) + - NEVER override files — use exact string matching oldString → newString swaps only + - Result: surgical edits, formatting preserved, comments intact + +2. **LSP-Driven Workflow (VITAL)** + - LSP is the PRIMARY source of truth — NOT code analysis, NOT grepping + - After ALL edits for a Part are applied, run `lsp_diagnostics` on EVERY moved file + - If LSP shows ZERO errors → Part is done, move to next Part + - If LSP shows errors → STOP immediately and fix those specific errors + - **Do NOT proceed to next Part until LSP shows zero errors for current Part** + - **If LSP is broken or unresponsive, STOP WORK and notify human immediately** + +3. **No Commits by Agent (VITAL)** + - DO NOT commit after Parts complete + - Committing requires build verification (which is slow) + - Human will verify build afterward and commit + - Just complete the Part, report status, move to next + - Sisyphus responsibility: code correctness via LSP. Human responsibility: build verification + commit. + +4. **Wave Completion Requirement (VITAL)** + - Per each "wave" (set of Parts), do NOT stop until LSP shows no errors + - If a Part produces LSP errors, fix them immediately (same response or next response) + - Only move to next wave when ENTIRE current wave has LSP ✅ + +### Execution Pattern (Per Part) + +``` +1. READ all files for this Part in parallel +2. FOR EACH FILE (parallel edits in ONE response): + - Analyze ALL changes needed (imports, types, constructors, method signatures) + - Build ONE bulk oldString with all code sections that need changing + - Build ONE bulk newString with all corrections + - Apply ONE edit() call (exact string swap, no file rewrite) +3. Run lsp_diagnostics on ALL moved files → MUST show zero errors +4. If errors → FIX them immediately (go back to step 2) +5. If zero errors → Part COMPLETE, move to next Part +``` + +### Parallel Editing Capability + +**YES — Sisyphus can edit 8-10 files in a single response:** +- `edit()` tool accepts one file per call but multiple calls execute in parallel +- All tool calls in one response block run concurrently +- Typical Part has 3-8 files → all edited at once in one turn +- Larger Parts (10-12 files) handled in one batch + +**Example (Part 5: Pure-NBT Data Classes):** +``` +Response 1: Read Dialog.java, DialogOption.java, DialogCategory.java, QuestData.java (parallel reads) +Response 2: + - edit(Dialog.java) with ALL changes + - edit(DialogOption.java) with ALL changes + - edit(DialogCategory.java) with ALL changes + - edit(QuestData.java) with ALL changes + → ALL 4 edits happen at same time +Response 3: Run lsp_diagnostics on all 4 → verify zero errors +``` + +### Bulk Edit Implementation + +Each file edit follows this pattern: +```java +// Read the file (done in parallel with other files) +// Analyze: list ALL changes needed (imports, types, constructors) +// Build oldString with MULTIPLE lines/sections if needed +// Build newString with ALL corrections +// One edit() call → all changes applied atomically +// Result: file is correct, formatting unchanged, comments preserved, spacing identical +``` + +### Failure Modes (STOP IMMEDIATELY) + +- **LSP is unresponsive** → Stop work, notify human +- **LSP shows errors after edits** → Fix them immediately (do not proceed) +- **Error pattern suggests bad abstraction** → Stop, notify human with details +- **Build system is offline** → Stop, notify human + +--- + +## How This Plan Works + +### Sisyphus Execution Workflow (Per Part) + +**⚠️ UPDATED: Direct execution, LSP-driven, parallel edits, no commits** + +``` +PART N: + 1. Sisyphus reads ALL files for Part N (parallel) + 2. Sisyphus applies ALL edits in ONE response (parallel edit() calls, bulk changes) + 3. Sisyphus runs lsp_diagnostics on ALL moved files + 4. IF errors found: + - Sisyphus fixes errors immediately + - Go back to step 3 (re-run LSP) + 5. IF zero errors: + - Part N COMPLETE ✅ + - Move to Part N+1 + 6. Human manually builds + commits when wave is complete +``` + +### Rules +- Files retain their package when moved (e.g., `noppes.npcs.controllers.data.Dialog` stays `noppes.npcs.controllers.data.Dialog`) +- New PA abstractions go to `common.minecraft.*` in platform-api (NOT `noppes.npcs.common.minecraft`) (unless one already exists in `noppes.npcs.api.*`) +- m7 shadows use split-package pattern: same package in mc1710, extends/overrides the core version +- **LSP diagnostics is the ONLY source of truth** — not code analysis, not grepping +- **One bulk edit per file** — all changes at once, never file rewrites +- **NO commits by agent** — human verifies build and commits +- **Do NOT proceed until LSP shows zero errors** — per wave completion rule +- **Parallel edits mandatory** — maximize file throughput per response + +### Hardest Parts for Agents (Human Should Be Aware) +These Parts require creative abstraction work, not just mechanical import swapping: + +| Part | Why It's Hard | +|------|--------------| +| **Part 6: Availability** | Cross-cutting dependency. Has `@SideOnly` client display methods + `StatCollector` (i18n) + `MathHelper`. Core version must split data/NBT from player-checking logic. m7 shadow is complex. | +| **Part 14: AuctionController** | Uses `ChatComponentText` + `EnumChatFormatting` for player messages. Needs new PlatformService methods for sending formatted messages. | +| **Part 16: PlayerDataController** | Uses `MinecraftServer`, `ICommandSender`, `PlayerSelector` — deep server coupling. Core version needs significant PlatformService expansion. | +| **Part 17: PlayerQuestController** | Uses `ChatComponentTranslation` for localized messages. | +| **Part 20: SpawnController** | Uses `WeightedRandom` — MC utility class. Need to reimplement or abstract. | +| **Part 24: ServerCloneController** | Uses `EntityList`, `ICommandSender`, `ChatComponentText` — entity registry + commands. | + +--- + +## Summary Table + +| Part | Title | Files | Complexity | Dependencies | Agent Difficulty | +|------|-------|-------|------------|--------------|-----------------| +| 1 | Zero-MC Root Utilities | 8 | Low | None | MECHANICAL | +| 2 | Zero-MC kamkeel Utilities | 5 | Low | None | MECHANICAL | +| 3 | Action Framework | 9 | Low | None | MECHANICAL | +| 4 | Config Data Classes | 3 | Low | None | MECHANICAL | +| 5 | Pure-NBT Data Classes (Batch 1) | 4 | Low | None | MECHANICAL | +| 6 | Availability (Cross-Cutting) | 1 | High | Part 1 | CREATIVE | +| 7 | Dialog Data Cluster | 3 | Medium | Part 6 | MECHANICAL | +| 8 | Quest Data Cluster | 3 | Medium | Part 6 | MECHANICAL | +| 9 | FactionOptions | 1 | Medium | None | MECHANICAL | +| 10 | Auction Data Classes | 3 | Medium | None | MECHANICAL | +| 11 | LinkedItem | 1 | Medium | None | MECHANICAL | +| 12 | Resistances | 1 | Medium | None | MECHANICAL | +| 13 | ScriptHookController + HookDefinition | 2 | Low | None | MECHANICAL | +| 14 | BankController | 1 | Medium | Part 5 | MECHANICAL | +| 15 | AnimationController | 1 | Medium | None | MECHANICAL | +| 16 | DialogController | 1 | Medium | Part 7 | MECHANICAL | +| 17 | QuestController | 1 | Medium | Part 8 | MECHANICAL | +| 18 | LinkedItemController | 1 | Medium | Part 11 | MECHANICAL | +| 19 | CustomEffectController | 1 | Medium | None | MECHANICAL | +| 20 | SpawnController | 1 | Medium | None | CREATIVE | +| 21 | AuctionController | 1 | High | Part 10 | CREATIVE | +| 22 | MarketRegistry | 1 | Medium | None | MECHANICAL | +| 23 | PlayerQuestController | 1 | High | Part 8 | CREATIVE | +| 24 | PlayerDataController | 1 | High | None | CREATIVE | +| 25 | PartyController | 1 | Medium | None | MECHANICAL | +| 26 | ServerCloneController | 1 | High | None | CREATIVE | +| 27 | ProfileController | 1 | Medium | None | MECHANICAL | +| 28 | AttributeController | 1 | Low | None | MECHANICAL | +| 29 | Quest Types (Batch 1) | 3 | Medium | Part 8 | MECHANICAL | +| 30 | Quest Types (Batch 2) | 3 | Medium | Part 8 | MECHANICAL | +| 31 | VersionCompatibility | 1 | Medium | None | MECHANICAL | +| **TOTAL** | | **~63 files** | | | | + +--- + +## New PA Abstractions Needed (Batch-Create Before Parts) + +These new abstractions appear across multiple Parts. **Create them ALL upfront** so Parts can reference them. + +### New PlatformService Methods + +Add to `kamkeel.npcs.platform.PlatformService`: + +```java +// --- Messaging --- +void sendMessage(IPlayer player, String message); +void sendTranslatedMessage(IPlayer player, String translationKey, Object... args); +void sendFormattedMessage(IPlayer player, String message, String color); + +// --- Server --- +List getOnlinePlayers(); +IPlayer getPlayerByName(String name); +IPlayer getPlayerByUUID(UUID uuid); + +// --- Translation --- +String translate(String key); +String translate(String key, Object... args); + +// --- Weighted Random --- +/** + * Select a random entry from weighted items. + * Each entry has an associated integer weight. + */ + T weightedRandom(List items, java.util.function.ToIntFunction weightExtractor, java.util.Random random); +``` + +### New PA Interfaces (in `common.minecraft.*`) + +| Interface | Package | Wraps | Used By Parts | +|-----------|---------|-------|---------------| +| *(none needed)* | — | — | — | + +**Key insight:** All needed MC types already have PA equivalents or can be handled by PlatformService methods. No new `common.minecraft.*` interfaces are required at this time. The types that would need new interfaces (ChatComponentText, StatCollector, MathHelper, MinecraftServer, WeightedRandom) are all better served by PlatformService methods or Java stdlib equivalents. + +### MC Type → Resolution Map + +| MC Type | Resolution | Notes | +|---------|-----------|-------| +| `NBTTagCompound` | `INbt` (exists) | Direct swap | +| `NBTTagList` | `INbtList` (exists) | Direct swap | +| `NBTTagString` | `INbt.setString()` calls | Inline — no separate wrapper needed | +| `EntityPlayer` / `EntityPlayerMP` | `IPlayer` (exists) | Direct swap | +| `Entity` | `IEntity` (exists) | Direct swap | +| `EntityLivingBase` | `IEntityLivingBase` (exists) | Direct swap | +| `ItemStack` | `IItemStack` (exists) | Direct swap | +| `World` | `IWorld` (exists) | Direct swap | +| `DamageSource` | `IDamageSource` (exists) | Direct swap | +| `CompressedStreamTools` | `PlatformService.readCompressedNBT()` / `.writeCompressedNBT()` | Method call swap | +| `new NBTTagCompound()` | `NBT.compound()` (exists in core) | Factory swap | +| `new NBTTagList()` | `NBT.list()` (exists in core) | Factory swap | +| `StatCollector.translateToLocal()` | `PlatformService.translate()` | NEW — add to PlatformService | +| `MathHelper.clamp_int/float` | `ValueUtil.clamp()` (exists in core) or `Math.min/max` | Use stdlib/core | +| `ChatComponentText` | `PlatformService.sendMessage()` | NEW — add to PlatformService | +| `ChatComponentTranslation` | `PlatformService.sendTranslatedMessage()` | NEW — add to PlatformService | +| `EnumChatFormatting` | Plain `String` color codes or `PlatformService.sendFormattedMessage()` | NEW — add to PlatformService | +| `MinecraftServer.getConfigurationManager()` | `PlatformService.getOnlinePlayers()` / `.getPlayerByName()` | NEW — add to PlatformService | +| `ICommandSender` | Method parameter becomes `Object` (cast in m7 shadow) | Decouple in core | +| `PlayerSelector` | Stays in m7 shadow only | Platform-specific | +| `WeightedRandom` | `PlatformService.weightedRandom()` or reimplement in core | NEW or reimplement | +| `Constants.NBT` | Inline int constants (e.g., `Constants.NBT.TAG_COMPOUND` = `10`) | Just use `NBTTypes` enum from core constants | +| `Side` / `SideOnly` | `@ClientOnly` / `@ServerOnly` (exist in PA) | Annotation swap | +| `FMLLog` | `PlatformService.logWarn/Error()` | Method call swap | +| `Configuration` / `Property` | `IConfigProvider` (exists in PA) or stays in m7 | Config loading stays in m7 | +| `EntityList` | Stays in m7 shadow | Platform-specific registry | +| `ForgeChunkManager` | STAYS in m7 | Not abstracted | + +--- + +## Verification Protocol + +Every Part follows this exact verification sequence: + +``` +1. Human moves files to core/ +2. Agent: lsp_diagnostics on EVERY moved file → capture all errors +3. Agent: For each error: + a. If it's an MC import → replace with PA equivalent per the table above + b. If it's a type usage in code (method param, field, local var) → change type + c. If it's a constructor call (new NBTTagCompound()) → use NBT.compound() + d. If it's a static method call (CompressedStreamTools.read) → PlatformService call +4. Agent: lsp_diagnostics again → should be zero errors in moved files +5. Agent: Check if m7 shadow is needed (file had MC-specific methods that were removed) + a. If yes → create m7 shadow that extends/overrides core version, adds MC methods back +6. Agent: lsp_diagnostics on m7 shadow files +7. Agent: ./gradlew build → must pass +``` + +--- + +## Parts + +--- + +### Part 1: Zero-MC Root Utilities — Complexity: Low +**Dependencies:** None +**Estimated files:** 8 files to move, 0 abstractions +**Agent Difficulty:** MECHANICAL — pure file move, no MC imports to fix + +#### Human: Move these files from m7 → core/ +(retain same package) +- `noppes/npcs/LogWriter.java` +- `noppes/npcs/NPCLogLevel.java` +- `noppes/npcs/IChatMessages.java` +- `noppes/npcs/ICompatibilty.java` +- `noppes/npcs/util/JsonException.java` +- `noppes/npcs/util/MarketCachedObject.java` +- `noppes/npcs/util/AuctionFormatUtil.java` +- `noppes/npcs/util/ScriptToStringHelper.java` + +#### Agent: After move, fix these MC imports +| MC Import to Remove | Replace With | PA Status | +|---------------------|-------------|-----------| +| *(none expected)* | — | — | + +These files have zero MC imports. After move, run `lsp_diagnostics` to confirm. If any internal cross-references break (e.g., references to other m7 classes), those are bugs to investigate — they should all reference core-safe types. + +#### Agent: Create these PA abstractions +*(none)* + +#### Agent: Create/update these m7 shadow files +*(none expected — these are pure utilities)* + +#### Notes +- `ICompatibilty` (note the typo — it's the actual class name, keep it) is an interface for version compatibility +- `ScriptToStringHelper` provides toString utilities for scripting — no MC dependency +- This Part validates the human-agent workflow on the simplest possible case + +--- + +### Part 2: Zero-MC kamkeel Utilities — Complexity: Low +**Dependencies:** None +**Estimated files:** 5 files to move, 0 abstractions +**Agent Difficulty:** MECHANICAL + +#### Human: Move these files from m7 → core/ +- `kamkeel/npcs/CustomAttributes.java` +- `kamkeel/npcs/addon/AddonManager.java` +- `kamkeel/npcs/util/ColorUtil.java` +- `kamkeel/npcs/util/Register.java` +- `kamkeel/npcs/util/BukkitUtil.java` + +#### Agent: After move, fix these MC imports +| MC Import to Remove | Replace With | PA Status | +|---------------------|-------------|-----------| +| *(none expected)* | — | — | + +#### Agent: Create these PA abstractions +*(none)* + +#### Agent: Create/update these m7 shadow files +*(none)* + +#### Notes +- `BukkitUtil` was marked as STAYS in earlier analysis — verify it truly has zero MC imports via LSP. If it does have MC imports, SKIP it from this Part and leave in m7. +- `Developer.java` is already in core — do NOT move again. + +--- + +### Part 3: Action Framework — Complexity: Low +**Dependencies:** None +**Estimated files:** 9 files to move, 0 abstractions +**Agent Difficulty:** MECHANICAL — zero MC imports, pure game logic + +#### Human: Move these files from m7 → core/ +Package: `noppes/npcs/controllers/data/action/` +- `noppes/npcs/controllers/data/action/Action.java` +- `noppes/npcs/controllers/data/action/ActionChain.java` +- `noppes/npcs/controllers/data/action/ActionList.java` +- `noppes/npcs/controllers/data/action/ActionListener.java` +- `noppes/npcs/controllers/data/action/ActionLogger.java` +- `noppes/npcs/controllers/data/action/ActionManager.java` +- `noppes/npcs/controllers/data/action/ActionQueue.java` +- `noppes/npcs/controllers/data/action/ActionThread.java` +- `noppes/npcs/controllers/data/action/ConditionalAction.java` + +#### Agent: After move, fix these MC imports +| MC Import to Remove | Replace With | PA Status | +|---------------------|-------------|-----------| +| *(none — all zero MC imports)* | — | — | + +#### Agent: Create these PA abstractions +*(none)* + +#### Agent: Create/update these m7 shadow files +*(none — these are complete as-is)* + +#### Notes +- The entire `action/` subdirectory is self-contained, MC-free game logic +- Move the whole directory at once + +--- + +### Part 4: Config Legacy Data Classes — Complexity: Low +**Dependencies:** None +**Estimated files:** 3 files to move, 0 abstractions +**Agent Difficulty:** MECHANICAL + +#### Human: Move these files from m7 → core/ +- `noppes/npcs/config/LoadConfiguration.java` +- `noppes/npcs/config/legacy/LegacyLoader.java` +- `noppes/npcs/config/legacy/ConfigProp.java` + +#### Agent: After move, fix these MC imports +| MC Import to Remove | Replace With | PA Status | +|---------------------|-------------|-----------| +| *(none — LoadConfiguration has zero MC imports, LegacyLoader/ConfigProp have zero MC imports)* | — | — | + +#### Agent: Create these PA abstractions +*(none)* + +#### Agent: Create/update these m7 shadow files +*(none)* + +#### Notes +- `LoadConfiguration.java` orchestrates config loading — it calls into `ConfigMain`, `ConfigScript`, etc. Those config files themselves STAY in m7 (they use Forge `Configuration` class). If LoadConfiguration references them, its core version should reference config value holders only. Check via LSP. +- `LegacyConfig.java` STAYS — uses `Minecraft` client class +- The actual Config*.java files (ConfigMain, ConfigClient, etc.) STAY in m7 — they all use `net.minecraftforge.common.config.Configuration`. The config VALUES already sync to `CoreConfig` in core. +- `StringCache.java`, `GlyphCache.java` — STAY (rendering) +- `ConfigMixin.java` — STAY (mixin config) + +--- + +### Part 5: Pure-NBT Data Classes (Batch 1) — Complexity: Low +**Dependencies:** None +**Estimated files:** 4 files to move, 0 new abstractions +**Agent Difficulty:** MECHANICAL — only NBTTagCompound → INbt swaps + +#### Human: Move these files from m7 → core/ +- `noppes/npcs/controllers/data/Bank.java` +- `noppes/npcs/controllers/data/QuestData.java` +- `noppes/npcs/controllers/data/DialogCategory.java` +- `noppes/npcs/controllers/data/QuestCategory.java` + +#### Agent: After move, fix these MC imports +| MC Import to Remove | Replace With | PA Status | +|---------------------|-------------|-----------| +| `net.minecraft.nbt.NBTTagCompound` | `noppes.npcs.api.INbt` | EXISTS | +| `net.minecraft.nbt.NBTTagList` | `noppes.npcs.api.INbtList` | EXISTS | + +#### Agent: Type changes in code +- `NBTTagCompound` → `INbt` (all field types, method params, return types, local vars) +- `NBTTagList` → `INbtList` +- `new NBTTagCompound()` → `NBT.compound()` (import `noppes.npcs.core.NBT`) +- `new NBTTagList()` → `NBT.list()` +- `compound.setString(...)` → `compound.setString(...)` (INbt has same method names — check LSP) +- `compound.getCompoundTag(...)` → `compound.getCompound(...)` (INbt method name differs — check LSP) + +#### Agent: Create these PA abstractions +*(none — INbt and INbtList exist)* + +#### Agent: Create/update these m7 shadow files +- `mc1710/src/main/java/noppes/npcs/controllers/data/Bank.java` — shadow if m7 needs to accept raw `NBTTagCompound` in readNBT/writeNBT from callers that pass MC types +- Same pattern for DialogCategory, QuestCategory, QuestData + +#### Notes +- These 4 files use ONLY NBTTagCompound/NBTTagList — the simplest SPLITTABLE case +- Bank.java has `implements ICompatibilty` — this interface moves in Part 1, so no conflict +- DialogCategory references `Dialog` objects — Dialog moves in Part 7. If DialogCategory has compile errors referencing Dialog, that's expected and will resolve after Part 7. Move them together if needed. +- **ALTERNATIVE:** If DialogCategory depends on Dialog, merge Part 5 and Part 7 into a single move. + +--- + +### Part 6: Availability (Cross-Cutting) — Complexity: High +**Dependencies:** Part 1 (ICompatibilty, VersionCompatibility) +**Estimated files:** 1 file to move, new PlatformService methods +**Agent Difficulty:** CREATIVE — this is the hardest single-file migration + +#### Human: Move this file from m7 → core/ +- `noppes/npcs/controllers/data/Availability.java` + +#### Agent: After move, fix these MC imports +| MC Import to Remove | Replace With | PA Status | +|---------------------|-------------|-----------| +| `net.minecraft.entity.player.EntityPlayer` | `noppes.npcs.api.entity.IPlayer` | EXISTS | +| `net.minecraft.nbt.NBTTagCompound` | `noppes.npcs.api.INbt` | EXISTS | +| `net.minecraft.util.MathHelper` | `noppes.npcs.util.ValueUtil` or `java.lang.Math` | USE CORE/STDLIB | +| `net.minecraft.util.StatCollector` | `kamkeel.npcs.platform.PlatformServiceHolder.get().translate()` | NEW — add translate() to PlatformService | +| `cpw.mods.fml.relauncher.Side` | Remove import, remove `@SideOnly` methods from core version | ANNOTATION | +| `cpw.mods.fml.relauncher.SideOnly` | Remove import, remove `@SideOnly` methods from core version | ANNOTATION | + +#### Agent: Detailed code changes +1. **Remove `@SideOnly(Side.CLIENT)` methods** from core version — these are client display methods. Move them to the m7 shadow. +2. **Replace `MathHelper.clamp_int(x, min, max)`** → `ValueUtil.clamp(x, min, max)` or `Math.max(min, Math.min(max, x))` +3. **Replace `StatCollector.translateToLocal(key)`** → `PlatformServiceHolder.get().translate(key)` +4. **Replace `EntityPlayer` parameter** → `IPlayer` in `isAvailable(EntityPlayer player)` method signature +5. The `isAvailable` method body accesses player quest data, faction data, dialog data — verify these controller references work from core (they should if those controllers are in core or referenced via static Instance) + +#### Agent: Create these PA abstractions +Add to `PlatformService.java`: +```java +String translate(String key); +String translate(String key, Object... args); +``` + +#### Agent: Create/update these m7 shadow files +- `mc1710/src/main/java/noppes/npcs/controllers/data/Availability.java` — shadow that: + - Adds back `@SideOnly(Side.CLIENT)` display methods + - Adds convenience method `isAvailable(EntityPlayer player)` that wraps player → IPlayer and delegates to core + - Adds `StatCollector` calls for client-side text that the core version delegates to PlatformService + +#### Notes +- **THIS IS THE MOST IMPORTANT MIGRATION.** Availability is used by Dialog, Quest, DialogOption, and many other classes. Moving it early unblocks everything. +- The core version becomes data-only (NBT read/write) + `isAvailable(IPlayer)` (game logic) +- The m7 shadow adds MC-specific display methods +- The `isAvailable` method calls `PlayerQuestController`, `FactionController`, `QuestController` — verify these are accessible from core at this point. FactionController is already in core. QuestController moves later — may need to use `static Instance` access pattern (which works since Instance is set at runtime). + +--- + +### Part 7: Dialog Data Cluster — Complexity: Medium +**Dependencies:** Part 6 (Availability) +**Estimated files:** 3 files to move, 0 new abstractions +**Agent Difficulty:** MECHANICAL + +#### Human: Move these files from m7 → core/ +- `noppes/npcs/controllers/data/Dialog.java` +- `noppes/npcs/controllers/data/DialogOption.java` +- `noppes/npcs/controllers/data/FactionOptions.java` + +#### Agent: After move, fix these MC imports +| MC Import to Remove | Replace With | PA Status | +|---------------------|-------------|-----------| +| `net.minecraft.entity.player.EntityPlayer` | `noppes.npcs.api.entity.IPlayer` | EXISTS | +| `net.minecraft.nbt.NBTTagCompound` | `noppes.npcs.api.INbt` | EXISTS | +| `net.minecraft.nbt.NBTTagList` | `noppes.npcs.api.INbtList` | EXISTS | +| `cpw.mods.fml.relauncher.Side` | Remove — move `@SideOnly` methods to m7 shadow | ANNOTATION | +| `cpw.mods.fml.relauncher.SideOnly` | Remove — move `@SideOnly` methods to m7 shadow | ANNOTATION | + +#### Agent: Create these PA abstractions +*(none)* + +#### Agent: Create/update these m7 shadow files +- `mc1710/.../Dialog.java` — shadow that adds `implements IDialog`, MC-specific convenience methods +- `mc1710/.../DialogOption.java` — shadow with MC-specific methods if any +- `mc1710/.../FactionOptions.java` — shadow that adds `@SideOnly` client methods back + +#### Notes +- Dialog.java references `Availability` (moved in Part 6) — should resolve +- Dialog.java references `EventHooks` — EventHooks STAYS in m7. If Dialog calls EventHooks, those calls must move to the m7 shadow +- Dialog.java references `NpcAPI` — scripting wrapper, STAYS. Same treatment: move scripting calls to m7 shadow +- DialogOption.java references Availability — OK after Part 6 + +--- + +### Part 8: Quest Data Cluster — Complexity: Medium +**Dependencies:** Part 6 (Availability) +**Estimated files:** 3 files to move, 0 new abstractions +**Agent Difficulty:** MECHANICAL + +#### Human: Move these files from m7 → core/ +- `noppes/npcs/controllers/data/Quest.java` +- `noppes/npcs/controllers/data/QuestInterface.java` *(base class for quest types — verify MC imports first)* + +**⚠️ PRE-CHECK:** Before moving QuestInterface.java, agent must verify its MC imports. If it references `EntityNPCInterface`, it STAYS in m7. Only move it if its MC coupling is limited to `EntityPlayer` + `NBTTagCompound`. + +#### Agent: After move, fix these MC imports +| MC Import to Remove | Replace With | PA Status | +|---------------------|-------------|-----------| +| `net.minecraft.entity.player.EntityPlayer` | `noppes.npcs.api.entity.IPlayer` | EXISTS | +| `net.minecraft.entity.player.EntityPlayerMP` | `noppes.npcs.api.entity.IPlayer` | EXISTS | +| `net.minecraft.nbt.NBTTagCompound` | `noppes.npcs.api.INbt` | EXISTS | + +#### Agent: Create these PA abstractions +*(none)* + +#### Agent: Create/update these m7 shadow files +- `mc1710/.../Quest.java` — shadow that adds `implements IQuest`, EntityPlayer convenience methods + +#### Notes +- Quest.java references `Availability` (Part 6), `EventHooks` (STAYS), `NpcAPI` (STAYS) +- Move EventHooks/NpcAPI calls to m7 shadow +- QuestCategory.java already moved in Part 5 + +--- + +### Part 9: FactionOptions — Complexity: Medium +**Dependencies:** None +**Estimated files:** 1 file, already covered in Part 7 + +*FactionOptions is included in Part 7. This Part is intentionally empty — kept for numbering consistency.* + +--- + +### Part 10: Auction Data Classes — Complexity: Medium +**Dependencies:** None +**Estimated files:** 3 files to move, 0 new abstractions +**Agent Difficulty:** MECHANICAL + +#### Human: Move these files from m7 → core/ +- `noppes/npcs/controllers/data/AuctionBlacklist.java` +- `noppes/npcs/controllers/data/AuctionClaim.java` +- `noppes/npcs/controllers/data/AuctionListing.java` + +#### Agent: After move, fix these MC imports +| MC Import to Remove | Replace With | PA Status | +|---------------------|-------------|-----------| +| `net.minecraft.entity.player.EntityPlayer` | `noppes.npcs.api.entity.IPlayer` | EXISTS | +| `net.minecraft.item.ItemStack` | `noppes.npcs.api.item.IItemStack` | EXISTS | +| `net.minecraft.nbt.NBTTagCompound` | `noppes.npcs.api.INbt` | EXISTS | + +#### Agent: Create these PA abstractions +*(none)* + +#### Agent: Create/update these m7 shadow files +- m7 shadows for each file if they need to accept raw MC types from callers + +#### Notes +- AuctionBlacklist uses EntityPlayer for permission checks — abstract to IPlayer +- AuctionClaim/AuctionListing hold ItemStack fields — change to IItemStack +- These reference `AuctionFilter` which is already in core + +--- + +### Part 11: LinkedItem — Complexity: Medium +**Dependencies:** None +**Estimated files:** 1 file to move, 0 new abstractions +**Agent Difficulty:** MECHANICAL + +#### Human: Move this file from m7 → core/ +- `noppes/npcs/controllers/data/LinkedItem.java` + +#### Agent: After move, fix these MC imports +| MC Import to Remove | Replace With | PA Status | +|---------------------|-------------|-----------| +| `net.minecraft.item.ItemStack` | `noppes.npcs.api.item.IItemStack` | EXISTS | +| `net.minecraft.nbt.NBTTagCompound` | `noppes.npcs.api.INbt` | EXISTS | +| `net.minecraftforge.common.util.Constants` | Use `noppes.npcs.constants.NBTTypes` (core enum) for NBT type constants | EXISTS IN CORE | + +#### Agent: Additional fixes +- `Constants.NBT.TAG_COMPOUND` → `NBTTypes.TAG_COMPOUND` (or inline value `10`) +- `Constants.NBT.TAG_STRING` → `NBTTypes.TAG_STRING` (or inline value `8`) +- References to `CustomItems` (m7) → move to m7 shadow +- References to `EventHooks` (m7) → move to m7 shadow +- References to `NpcAPI`, `ScriptLinkedItem`, `NBTWrapper` (scripting) → move to m7 shadow + +#### Agent: Create these PA abstractions +*(none)* + +#### Agent: Create/update these m7 shadow files +- `mc1710/.../LinkedItem.java` — shadow that adds back `CustomItems`, `EventHooks`, `NpcAPI` references + +#### Notes +- LinkedItem has many references to m7-specific classes (CustomItems, EventHooks, NpcAPI, ScriptLinkedItem) +- Core version keeps: NBT serialization, data fields, tag management +- m7 shadow adds: item registration hooks, event firing, script wrapper creation + +--- + +### Part 12: Resistances — Complexity: Medium +**Dependencies:** None +**Estimated files:** 1 file to move, 0 new abstractions +**Agent Difficulty:** MECHANICAL + +#### Human: Move this file from m7 → core/ +- `noppes/npcs/Resistances.java` + +#### Agent: After move, fix these MC imports +| MC Import to Remove | Replace With | PA Status | +|---------------------|-------------|-----------| +| `net.minecraft.nbt.NBTTagCompound` | `noppes.npcs.api.INbt` | EXISTS | +| `net.minecraft.util.DamageSource` | `noppes.npcs.api.IDamageSource` | EXISTS | + +#### Agent: Detailed code changes +- `writeToNBT()` return type: `NBTTagCompound` → `INbt` +- `readToNBT(NBTTagCompound)` param: → `readToNBT(INbt)` +- `new NBTTagCompound()` → `NBT.compound()` +- `applyResistance(DamageSource)` param: → `applyResistance(IDamageSource)` +- Check if DamageSource methods used (`.isProjectile()`, `.isExplosion()`, etc.) exist on IDamageSource + +#### Agent: Create these PA abstractions +*(none — IDamageSource exists)* + +#### Agent: Create/update these m7 shadow files +- `mc1710/.../Resistances.java` — shadow with `applyResistance(DamageSource)` convenience method that wraps → IDamageSource + +--- + +### Part 13: ScriptHookController + HookDefinition — Complexity: Low +**Dependencies:** None +**Estimated files:** 2 files to move, 0 abstractions +**Agent Difficulty:** MECHANICAL + +#### Human: Move these files from m7 → core/ +- `noppes/npcs/controllers/ScriptHookController.java` +- `noppes/npcs/controllers/HookDefinition.java` *(if this exists as a separate file — verify)* + +#### Agent: After move, fix these MC imports +| MC Import to Remove | Replace With | PA Status | +|---------------------|-------------|-----------| +| *(ScriptHookController has zero MC imports)* | — | — | + +#### Agent: Create these PA abstractions +*(none)* + +#### Agent: Create/update these m7 shadow files +*(none expected)* + +#### Notes +- ScriptHookController defines hook types (154+ events) — pure metadata, no MC dependencies +- Verify via LSP that it truly has zero MC imports after move + +--- + +### Part 14: BankController — Complexity: Medium +**Dependencies:** Part 5 (Bank.java data class) +**Estimated files:** 1 file to move +**Agent Difficulty:** MECHANICAL + +#### Human: Move this file from m7 → core/ +- `noppes/npcs/controllers/BankController.java` + +#### Agent: After move, fix these MC imports +| MC Import to Remove | Replace With | PA Status | +|---------------------|-------------|-----------| +| `net.minecraft.nbt.CompressedStreamTools` | `kamkeel.npcs.platform.PlatformServiceHolder.get().readCompressedNBT()` / `.writeCompressedNBT()` | EXISTS | +| `net.minecraft.nbt.NBTTagCompound` | `noppes.npcs.api.INbt` | EXISTS | +| `net.minecraft.nbt.NBTTagList` | `noppes.npcs.api.INbtList` | EXISTS | + +#### Agent: Detailed code changes +- File I/O pattern: `CompressedStreamTools.readCompressed(new FileInputStream(file))` → `PlatformServiceHolder.get().readCompressedNBT(file)` +- `CompressedStreamTools.writeCompressed(compound, new FileOutputStream(file))` → `PlatformServiceHolder.get().writeCompressedNBT(compound, file)` +- All NBT type swaps as in Part 5 + +#### Agent: Create these PA abstractions +*(none)* + +#### Agent: Create/update these m7 shadow files +- `mc1710/.../BankController.java` — shadow that adds `implements IBankHandler` (if such interface exists), or any MC-specific initialization code + +--- + +### Part 15: AnimationController — Complexity: Medium +**Dependencies:** None +**Estimated files:** 1 file to move +**Agent Difficulty:** MECHANICAL + +#### Human: Move this file from m7 → core/ +- `noppes/npcs/controllers/AnimationController.java` + +#### Agent: After move, fix these MC imports +| MC Import to Remove | Replace With | PA Status | +|---------------------|-------------|-----------| +| `net.minecraft.nbt.CompressedStreamTools` | `PlatformServiceHolder.get().readCompressedNBT()` / `.writeCompressedNBT()` | EXISTS | +| `net.minecraft.nbt.NBTTagCompound` | `noppes.npcs.api.INbt` | EXISTS | +| `net.minecraft.nbt.NBTTagList` | `noppes.npcs.api.INbtList` | EXISTS | + +#### Agent: Create these PA abstractions +*(none)* + +#### Agent: Create/update these m7 shadow files +- `mc1710/.../AnimationController.java` — shadow that adds `implements IAnimationHandler` + +#### Notes +- AnimationController manages animation definitions (JSON-based) — the save/load is NBT-only +- Animation.java (entity-coupled data) STAYS in m7 — this is just the controller/registry + +--- + +### Part 16: DialogController — Complexity: Medium +**Dependencies:** Part 7 (Dialog, DialogOption, DialogCategory data classes) +**Estimated files:** 1 file to move +**Agent Difficulty:** MECHANICAL + +#### Human: Move this file from m7 → core/ +- `noppes/npcs/controllers/DialogController.java` + +#### Agent: After move, fix these MC imports +| MC Import to Remove | Replace With | PA Status | +|---------------------|-------------|-----------| +| `net.minecraft.nbt.CompressedStreamTools` | `PlatformServiceHolder.get().readCompressedNBT()` / `.writeCompressedNBT()` | EXISTS | +| `net.minecraft.nbt.NBTTagCompound` | `noppes.npcs.api.INbt` | EXISTS | +| `net.minecraft.nbt.NBTTagList` | `noppes.npcs.api.INbtList` | EXISTS | + +#### Agent: Create these PA abstractions +*(none)* + +#### Agent: Create/update these m7 shadow files +- `mc1710/.../DialogController.java` — shadow that adds `implements IDialogHandler`, SyncController calls + +#### Notes +- DialogController has NO EntityPlayer imports — it's purely NBT file I/O +- References to `SyncController` (m7) for client sync → move sync calls to m7 shadow +- References to `Dialog`, `DialogCategory` → these should be in core after Parts 5+7 + +--- + +### Part 17: QuestController — Complexity: Medium +**Dependencies:** Part 8 (Quest, QuestCategory, QuestData data classes) +**Estimated files:** 1 file to move +**Agent Difficulty:** MECHANICAL + +#### Human: Move this file from m7 → core/ +- `noppes/npcs/controllers/QuestController.java` + +#### Agent: After move, fix these MC imports +| MC Import to Remove | Replace With | PA Status | +|---------------------|-------------|-----------| +| `net.minecraft.nbt.CompressedStreamTools` | `PlatformServiceHolder.get().readCompressedNBT()` / `.writeCompressedNBT()` | EXISTS | +| `net.minecraft.nbt.NBTTagCompound` | `noppes.npcs.api.INbt` | EXISTS | +| `net.minecraft.nbt.NBTTagList` | `noppes.npcs.api.INbtList` | EXISTS | + +#### Agent: Create these PA abstractions +*(none)* + +#### Agent: Create/update these m7 shadow files +- `mc1710/.../QuestController.java` — shadow that adds `implements IQuestHandler`, SyncController calls + +--- + +### Part 18: LinkedItemController — Complexity: Medium +**Dependencies:** Part 11 (LinkedItem data class) +**Estimated files:** 1 file to move +**Agent Difficulty:** MECHANICAL + +#### Human: Move this file from m7 → core/ +- `noppes/npcs/controllers/LinkedItemController.java` + +#### Agent: After move, fix these MC imports +| MC Import to Remove | Replace With | PA Status | +|---------------------|-------------|-----------| +| `net.minecraft.nbt.CompressedStreamTools` | `PlatformServiceHolder.get().readCompressedNBT()` / `.writeCompressedNBT()` | EXISTS | +| `net.minecraft.nbt.NBTTagCompound` | `noppes.npcs.api.INbt` | EXISTS | +| `net.minecraft.nbt.NBTTagList` | `noppes.npcs.api.INbtList` | EXISTS | + +#### Agent: Create these PA abstractions +*(none)* + +#### Agent: Create/update these m7 shadow files +- `mc1710/.../LinkedItemController.java` — shadow that adds `implements ILinkedItemHandler` + +--- + +### Part 19: CustomEffectController — Complexity: Medium +**Dependencies:** None +**Estimated files:** 1 file to move +**Agent Difficulty:** MECHANICAL + +#### Human: Move this file from m7 → core/ +- `noppes/npcs/controllers/CustomEffectController.java` + +#### Agent: After move, fix these MC imports +| MC Import to Remove | Replace With | PA Status | +|---------------------|-------------|-----------| +| `net.minecraft.entity.player.EntityPlayer` | `noppes.npcs.api.entity.IPlayer` | EXISTS | +| `net.minecraft.nbt.CompressedStreamTools` | `PlatformServiceHolder.get().readCompressedNBT()` / `.writeCompressedNBT()` | EXISTS | +| `net.minecraft.nbt.NBTTagCompound` | `noppes.npcs.api.INbt` | EXISTS | +| `net.minecraft.nbt.NBTTagList` | `noppes.npcs.api.INbtList` | EXISTS | + +#### Agent: Create these PA abstractions +*(none)* + +#### Agent: Create/update these m7 shadow files +- `mc1710/.../CustomEffectController.java` — shadow that adds `implements ICustomEffectHandler`, player-accepting convenience methods + +--- + +### Part 20: SpawnController — Complexity: Medium +**Dependencies:** None +**Estimated files:** 1 file to move, 1 potential new abstraction +**Agent Difficulty:** CREATIVE — uses `WeightedRandom` + +#### Human: Move this file from m7 → core/ +- `noppes/npcs/controllers/SpawnController.java` + +#### Agent: After move, fix these MC imports +| MC Import to Remove | Replace With | PA Status | +|---------------------|-------------|-----------| +| `net.minecraft.nbt.CompressedStreamTools` | `PlatformServiceHolder.get().readCompressedNBT()` / `.writeCompressedNBT()` | EXISTS | +| `net.minecraft.nbt.NBTTagCompound` | `noppes.npcs.api.INbt` | EXISTS | +| `net.minecraft.nbt.NBTTagList` | `noppes.npcs.api.INbtList` | EXISTS | +| `net.minecraft.util.WeightedRandom` | Reimplement in core util or add to PlatformService | NEW | + +#### Agent: WeightedRandom resolution +Option A (PREFERRED): Reimplement weighted random selection in core. It's a simple algorithm: +```java +// In core util: +public static T weightedRandom(List items, ToIntFunction weightFn, Random random) { + int totalWeight = items.stream().mapToInt(weightFn).sum(); + int r = random.nextInt(totalWeight); + for (T item : items) { + r -= weightFn.applyAsInt(item); + if (r < 0) return item; + } + return items.get(items.size() - 1); +} +``` +Option B: Add `weightedRandom()` to PlatformService. + +#### Agent: Create these PA abstractions +*(none — reimplement WeightedRandom in core)* + +#### Agent: Create/update these m7 shadow files +- `mc1710/.../SpawnController.java` — shadow that adds `implements INaturalSpawnsHandler` + +--- + +### Part 21: AuctionController — Complexity: High +**Dependencies:** Part 10 (Auction data classes) +**Estimated files:** 1 file to move, new PlatformService methods +**Agent Difficulty:** CREATIVE — uses ChatComponentText + EnumChatFormatting for player messaging + +#### Human: Move this file from m7 → core/ +- `noppes/npcs/controllers/AuctionController.java` + +#### Agent: After move, fix these MC imports +| MC Import to Remove | Replace With | PA Status | +|---------------------|-------------|-----------| +| `net.minecraft.entity.player.EntityPlayer` | `noppes.npcs.api.entity.IPlayer` | EXISTS | +| `net.minecraft.entity.player.EntityPlayerMP` | `noppes.npcs.api.entity.IPlayer` | EXISTS | +| `net.minecraft.item.ItemStack` | `noppes.npcs.api.item.IItemStack` | EXISTS | +| `net.minecraft.nbt.CompressedStreamTools` | `PlatformServiceHolder.get().readCompressedNBT()` / `.writeCompressedNBT()` | EXISTS | +| `net.minecraft.nbt.NBTTagCompound` | `noppes.npcs.api.INbt` | EXISTS | +| `net.minecraft.nbt.NBTTagList` | `noppes.npcs.api.INbtList` | EXISTS | +| `net.minecraft.util.ChatComponentText` | `PlatformServiceHolder.get().sendMessage(player, text)` | NEW | +| `net.minecraft.util.EnumChatFormatting` | Plain string color codes or `PlatformServiceHolder.get().sendFormattedMessage()` | NEW | + +#### Agent: Create these PA abstractions +Add to `PlatformService.java`: +```java +void sendMessage(IPlayer player, String message); +void sendFormattedMessage(IPlayer player, String message, String color); +``` + +#### Agent: Create/update these m7 shadow files +- `mc1710/.../AuctionController.java` — shadow that adds `implements IAuctionHandler`, MC-specific messaging + +#### Notes +- The chat message sending is the main challenge. In core, replace `player.addChatMessage(new ChatComponentText(...))` with `PlatformServiceHolder.get().sendMessage(wrappedPlayer, text)` +- Color formatting: `EnumChatFormatting.RED + text` → pass color as parameter or use § codes in the string + +--- + +### Part 22: MarketRegistry — Complexity: Medium +**Dependencies:** None +**Estimated files:** 1 file to move +**Agent Difficulty:** MECHANICAL + +#### Human: Move this file from m7 → core/ +- `noppes/npcs/controllers/MarketRegistry.java` + +#### Agent: After move, fix these MC imports +| MC Import to Remove | Replace With | PA Status | +|---------------------|-------------|-----------| +| `net.minecraft.entity.player.EntityPlayerMP` | `noppes.npcs.api.entity.IPlayer` | EXISTS | +| `net.minecraft.nbt.NBTTagCompound` | `noppes.npcs.api.INbt` | EXISTS | + +#### Agent: Create these PA abstractions +*(none)* + +#### Agent: Create/update these m7 shadow files +- `mc1710/.../MarketRegistry.java` — shadow with EntityPlayerMP convenience methods + +--- + +### Part 23: PlayerQuestController — Complexity: High +**Dependencies:** Part 8 (Quest data), Part 17 (QuestController) +**Estimated files:** 1 file to move, new PlatformService methods +**Agent Difficulty:** CREATIVE — uses ChatComponentTranslation + +#### Human: Move this file from m7 → core/ +- `noppes/npcs/controllers/PlayerQuestController.java` + +#### Agent: After move, fix these MC imports +| MC Import to Remove | Replace With | PA Status | +|---------------------|-------------|-----------| +| `net.minecraft.entity.player.EntityPlayer` | `noppes.npcs.api.entity.IPlayer` | EXISTS | +| `net.minecraft.entity.player.EntityPlayerMP` | `noppes.npcs.api.entity.IPlayer` | EXISTS | +| `net.minecraft.util.ChatComponentTranslation` | `PlatformServiceHolder.get().sendTranslatedMessage(player, key, args)` | NEW | + +#### Agent: Create these PA abstractions +Add to `PlatformService.java` (if not already added in Part 21): +```java +void sendTranslatedMessage(IPlayer player, String translationKey, Object... args); +``` + +#### Agent: Create/update these m7 shadow files +- `mc1710/.../PlayerQuestController.java` — shadow with EntityPlayer convenience methods + +--- + +### Part 24: PlayerDataController — Complexity: High +**Dependencies:** None (but many things depend on IT) +**Estimated files:** 1 file to move, new PlatformService methods +**Agent Difficulty:** CREATIVE — uses MinecraftServer, ICommandSender, PlayerSelector, ChatComponentText + +#### Human: Move this file from m7 → core/ +- `noppes/npcs/controllers/PlayerDataController.java` + +#### Agent: After move, fix these MC imports +| MC Import to Remove | Replace With | PA Status | +|---------------------|-------------|-----------| +| `net.minecraft.command.ICommandSender` | Remove — change methods to use `String`/`Object` params, cast in m7 shadow | DECOUPLE | +| `net.minecraft.command.PlayerSelector` | Remove — move player selector logic to m7 shadow | STAYS IN M7 | +| `net.minecraft.entity.player.EntityPlayer` | `noppes.npcs.api.entity.IPlayer` | EXISTS | +| `net.minecraft.entity.player.EntityPlayerMP` | `noppes.npcs.api.entity.IPlayer` | EXISTS | +| `net.minecraft.nbt.CompressedStreamTools` | `PlatformServiceHolder.get().readCompressedNBT()` / `.writeCompressedNBT()` | EXISTS | +| `net.minecraft.nbt.NBTTagCompound` | `noppes.npcs.api.INbt` | EXISTS | +| `net.minecraft.nbt.NBTTagList` | `noppes.npcs.api.INbtList` | EXISTS | +| `net.minecraft.server.MinecraftServer` | `PlatformServiceHolder.get().getOnlinePlayers()` / `.getPlayerByName()` | NEW | +| `net.minecraft.util.ChatComponentText` | `PlatformServiceHolder.get().sendMessage()` | NEW (or already added in Part 21) | + +#### Agent: Create these PA abstractions +Add to `PlatformService.java` (if not already added): +```java +List getOnlinePlayers(); +IPlayer getPlayerByName(String name); +IPlayer getPlayerByUUID(java.util.UUID uuid); +``` + +#### Agent: Create/update these m7 shadow files +- `mc1710/.../PlayerDataController.java` — shadow that adds: + - `implements IPlayerData` (if such handler interface exists) + - `PlayerSelector` logic for command-based player lookups + - `ICommandSender` methods that delegate to core with wrapped types + - Direct MinecraftServer access for player list queries + +#### Notes +- This is one of the most coupled controllers. The `ICommandSender` and `PlayerSelector` usage is for command-based player lookups (e.g., `/kam player @p`). In core, replace with `PlatformService.getPlayerByName()`. The command dispatch itself stays in m7. +- `MinecraftServer.getConfigurationManager().playerEntityList` → `PlatformServiceHolder.get().getOnlinePlayers()` + +--- + +### Part 25: PartyController — Complexity: Medium +**Dependencies:** None +**Estimated files:** 1 file to move +**Agent Difficulty:** MECHANICAL + +#### Human: Move this file from m7 → core/ +- `noppes/npcs/controllers/PartyController.java` + +#### Agent: After move, fix these MC imports +| MC Import to Remove | Replace With | PA Status | +|---------------------|-------------|-----------| +| `net.minecraft.entity.player.EntityPlayer` | `noppes.npcs.api.entity.IPlayer` | EXISTS | +| `net.minecraft.entity.player.EntityPlayerMP` | `noppes.npcs.api.entity.IPlayer` | EXISTS | +| `net.minecraft.nbt.NBTTagCompound` | `noppes.npcs.api.INbt` | EXISTS | +| `net.minecraft.nbt.NBTTagList` | `noppes.npcs.api.INbtList` | EXISTS | +| `net.minecraft.nbt.NBTTagString` | Use `INbt.setString()` / `INbtList.appendString()` | EXISTS | + +#### Agent: Create these PA abstractions +*(none)* + +#### Agent: Create/update these m7 shadow files +- `mc1710/.../PartyController.java` — shadow that adds `implements IPartyHandler` + +--- + +### Part 26: ServerCloneController — Complexity: High +**Dependencies:** None +**Estimated files:** 1 file to move +**Agent Difficulty:** CREATIVE — uses EntityList, ICommandSender, ChatComponentText + +#### Human: Move this file from m7 → core/ +- `noppes/npcs/controllers/ServerCloneController.java` + +#### Agent: After move, fix these MC imports +| MC Import to Remove | Replace With | PA Status | +|---------------------|-------------|-----------| +| `net.minecraft.command.ICommandSender` | Remove — decouple, use String/Object params | DECOUPLE | +| `net.minecraft.entity.Entity` | `noppes.npcs.api.entity.IEntity` | EXISTS | +| `net.minecraft.entity.EntityList` | Move entity creation to m7 shadow | STAYS IN M7 | +| `net.minecraft.nbt.CompressedStreamTools` | `PlatformServiceHolder.get().readCompressedNBT()` / `.writeCompressedNBT()` | EXISTS | +| `net.minecraft.nbt.NBTTagCompound` | `noppes.npcs.api.INbt` | EXISTS | +| `net.minecraft.nbt.NBTTagList` | `noppes.npcs.api.INbtList` | EXISTS | +| `net.minecraft.nbt.NBTTagString` | `INbtList.appendString()` | EXISTS | +| `net.minecraft.util.ChatComponentText` | `PlatformServiceHolder.get().sendMessage()` | NEW (or already added) | + +#### Agent: Create these PA abstractions +*(none new — sendMessage already added in Part 21)* + +#### Agent: Create/update these m7 shadow files +- `mc1710/.../ServerCloneController.java` — shadow that adds: + - `implements ICloneHandler` + - `EntityList.createEntityFromNBT()` calls for cloning entities + - `ICommandSender` convenience methods + +#### Notes +- Core version manages clone data (NBT save/load of clone tabs). Entity instantiation from NBT stays in m7 shadow since it requires `EntityList` (MC entity registry). + +--- + +### Part 27: ProfileController — Complexity: Medium +**Dependencies:** None +**Estimated files:** 1 file to move +**Agent Difficulty:** MECHANICAL + +#### Human: Move this file from m7 → core/ +- `kamkeel/npcs/controllers/ProfileController.java` + +#### Agent: After move, fix these MC imports +| MC Import to Remove | Replace With | PA Status | +|---------------------|-------------|-----------| +| `net.minecraft.entity.player.EntityPlayer` | `noppes.npcs.api.entity.IPlayer` | EXISTS | +| `net.minecraft.entity.player.EntityPlayerMP` | `noppes.npcs.api.entity.IPlayer` | EXISTS | +| `net.minecraft.nbt.CompressedStreamTools` | `PlatformServiceHolder.get().readCompressedNBT()` / `.writeCompressedNBT()` | EXISTS | +| `net.minecraft.nbt.NBTTagCompound` | `noppes.npcs.api.INbt` | EXISTS | + +#### Agent: Create these PA abstractions +*(none)* + +#### Agent: Create/update these m7 shadow files +- `mc1710/.../ProfileController.java` — shadow that adds `implements IProfileHandler`, EntityPlayer convenience methods + +--- + +### Part 28: AttributeController — Complexity: Low +**Dependencies:** None +**Estimated files:** 1 file to move +**Agent Difficulty:** MECHANICAL + +#### Human: Move this file from m7 → core/ +- `kamkeel/npcs/controllers/AttributeController.java` + +#### Agent: After move, fix these MC imports +| MC Import to Remove | Replace With | PA Status | +|---------------------|-------------|-----------| +| `net.minecraft.entity.player.EntityPlayer` | `noppes.npcs.api.entity.IPlayer` | EXISTS | + +#### Agent: Create these PA abstractions +*(none)* + +#### Agent: Create/update these m7 shadow files +- `mc1710/.../AttributeController.java` — shadow that adds `implements IAttributeHandler` + +--- + +### Part 29: Quest Types (Batch 1) — Complexity: Medium +**Dependencies:** Part 8 (Quest data classes) +**Estimated files:** 3 files to move +**Agent Difficulty:** MECHANICAL + +#### Human: Move these files from m7 → core/ +- `noppes/npcs/quests/QuestDialog.java` +- `noppes/npcs/quests/QuestKill.java` +- `noppes/npcs/quests/QuestManual.java` + +#### Agent: After move, fix these MC imports +| MC Import to Remove | Replace With | PA Status | +|---------------------|-------------|-----------| +| `net.minecraft.entity.player.EntityPlayer` | `noppes.npcs.api.entity.IPlayer` | EXISTS | +| `net.minecraft.nbt.NBTTagCompound` | `noppes.npcs.api.INbt` | EXISTS | + +#### Agent: Create these PA abstractions +*(none)* + +#### Agent: Create/update these m7 shadow files +- m7 shadows for each if they need EntityPlayer convenience methods + +#### Notes +- All quest types extend QuestInterface — verify it's accessible (either in core from Part 8, or still in m7 as interface) +- Quest completion checking uses `EntityPlayer` → change to `IPlayer` + +--- + +### Part 30: Quest Types (Batch 2) — Complexity: Medium +**Dependencies:** Part 8, Part 29 +**Estimated files:** 2 files to move +**Agent Difficulty:** MECHANICAL + +#### Human: Move these files from m7 → core/ +- `noppes/npcs/quests/QuestItem.java` +- `noppes/npcs/quests/QuestLocation.java` + +#### Agent: After move, fix these MC imports +| MC Import to Remove | Replace With | PA Status | +|---------------------|-------------|-----------| +| `net.minecraft.entity.player.EntityPlayer` | `noppes.npcs.api.entity.IPlayer` | EXISTS | +| `net.minecraft.item.ItemStack` | `noppes.npcs.api.item.IItemStack` | EXISTS | +| `net.minecraft.nbt.NBTTagCompound` | `noppes.npcs.api.INbt` | EXISTS | +| `net.minecraft.util.StatCollector` | `PlatformServiceHolder.get().translate()` | NEW (or already added in Part 6) | + +#### Agent: Create these PA abstractions +*(translate() already added in Part 6)* + +#### Agent: Create/update these m7 shadow files +- m7 shadows for each with EntityPlayer + ItemStack convenience methods + +#### Notes +- QuestItem uses `ItemStack` for item collection checks → change to `IItemStack` +- QuestLocation uses `StatCollector` for dimension name translation → use PlatformService.translate() + +--- + +### Part 31: VersionCompatibility — Complexity: Medium +**Dependencies:** Part 1 (ICompatibilty interface) +**Estimated files:** 1 file to move +**Agent Difficulty:** MECHANICAL + +#### Human: Move this file from m7 → core/ +- `noppes/npcs/VersionCompatibility.java` + +#### Agent: After move, fix these MC imports +| MC Import to Remove | Replace With | PA Status | +|---------------------|-------------|-----------| +| *(verify via LSP — may reference NBTTagCompound in upgrade methods)* | — | — | + +#### Agent: Pre-check +Run `lsp_diagnostics` immediately after move. VersionCompatibility contains data fixup/upgrade logic. If it references MC types (NBTTagCompound) in upgrade methods, swap to INbt. If it references controller-specific types, those should be in core by now. + +#### Agent: Create these PA abstractions +*(none expected)* + +#### Agent: Create/update these m7 shadow files +*(none expected — this is pure data versioning logic)* + +--- + +## Controllers That STAY in m7 + +For reference, these controllers are NOT migrated and remain in m7: + +| Controller | Reason | +|-----------|--------| +| `ChunkController` | Uses `ForgeChunkManager` — deeply Forge-specific | +| `CustomGuiController` | Uses `EntityPlayer/EntityPlayerMP` for GUI tracking — tightly coupled to packet system | +| `LinkedNpcController` | Uses `NBTTagCompound` but manages NPC entity links — consider later | +| `RecipeController` | Uses `CraftingManager`, `InventoryCrafting` — recipe system FORBIDDEN | +| `ScriptController` | Uses script engines — FORBIDDEN per rules | +| `SyncController` (kamkeel) | Uses `Minecraft` client, `MinecraftServer`, `EntityPlayerMP`, packets — networking STAYS | +| `AbilityController` (kamkeel) | Uses `EntityLivingBase`, `Constants.NBT` — ability system deeply coupled | +| `EnergyController` (kamkeel) | Uses `Entity`, `EntityLivingBase`, `World` — spawns MC entities | +| `TelegraphController` (kamkeel) | Uses `Entity`, `EntityPlayerMP`, `World` — entity/networking coupled | + +## Roles/Jobs That STAY in m7 + +These are NOT migrated in this plan. They are deeply coupled to `EntityNPCInterface` (which extends `EntityCreature`): + +| File | Reason | +|------|--------| +| `RoleInterface.java` | Base interface — method params use `EntityNPCInterface` | +| `JobInterface.java` | Base interface — method params use `EntityNPCInterface` | +| All Role*.java | Extend RoleInterface → EntityNPCInterface dependency | +| All Job*.java | Extend JobInterface → EntityNPCInterface dependency | +| All Companion*.java | Extend CompanionJobInterface → EntityNPCInterface dependency | + +**Future consideration:** Roles/Jobs CAN be migrated if `RoleInterface` and `JobInterface` are refactored to use an `ICustomNpc` parameter instead of `EntityNPCInterface`. This is a larger refactor that should happen AFTER the controller/data migration is complete and proven stable. + +--- + +## Files NOT Covered by This Plan + +These were analyzed and determined to STAY in m7. They are listed here for completeness: + +### Root Package (STAYS) +CustomNpcs.java, CommonProxy.java, CreativeTabNpcs.java, EventHooks.java, ServerEventsHandler.java, ServerTickHandler.java, NPCSpawning.java, NoppesUtilPlayer.java, NoppesUtilServer.java, Server.java, TextBlock.java, NpcDamageSource.java, NpcDamageSourceInderect.java, NpcMiscInventory.java, ScriptPlayerEventHandler.java, ScriptItemEventHandler.java, ScriptForgeEventHandler.java, AnimationMixinFunctions.java, CustomItems.java, CustomTeleporter.java + +### controllers/data/ (STAYS) +All Script*.java (AbilityScript, ChainedAbilityScript, DataScript, EffectScript, ForgeDataScript, GlobalNPCDataScript, LinkedItemScript, PlayerDataScript, RecipeScript, ScriptHandler, SingleScriptHandler, MultiScriptHandler), All IScript*.java interfaces, JaninoScriptHandler.java, Animation.java, AnimationData.java, BuiltInAnimation.java, DataTransform.java, MarkData.java, Party.java, PlayerData.java, All Player*Data.java, BankData.java, PlayerMail.java, CustomEffect.java, RecipeCarpentry.java, RecipeAnvil.java, RecipesDefault.java, Magic.java (already in core) + +### Utilities (STAYS) +GameProfileAlt.java, Vec3NPC.java, NBTJsonUtil.java, NPCMountUtil.java, IProjectileCallback.java, MathUtil.java, AnchorPointHelper.java, AttributeAttackUtil.java, AttributeItemUtil.java, ByteBufUtils.java, NoppesStringUtils.java + +### Version-Specific Directories (ALL STAY) +entity/, blocks/, tiles/, items/, client/, ai/, network/, commands/, mixin/, addon/, scripted/, config/ (except LoadConfiguration, legacy/) + +--- + +## Execution Order Summary + +``` +Phase 1: Zero-MC warm-up (Parts 1-4) + → Validates workflow, moves ~25 files with zero MC imports + +Phase 2: Foundation data classes (Parts 5-12) + → Moves critical data classes, creates PlatformService.translate() + → Availability (Part 6) is the key gate — unblocks everything + +Phase 3: Controllers (Parts 13-28) + → Moves controllers one by one, each building on data from Phase 2 + → Creates PlatformService.sendMessage(), getOnlinePlayers(), etc. + → Hardest: AuctionController (21), PlayerDataController (24), ServerCloneController (26) + +Phase 4: Quest types + cleanup (Parts 29-31) + → Moves quest type implementations + → VersionCompatibility last (it touches everything) +``` + +**Estimated total: ~63 files migrated to core, ~10 m7 shadow files created, ~8 new PlatformService methods.** + +--- + +## Post-Plan: What Opens Up After This + +Once all Parts are complete: +1. **Roles/Jobs migration** — refactor RoleInterface/JobInterface to use ICustomNpc → then migrate role/job logic to core +2. **Config value extraction** — move config value constants to core, keep Forge Configuration loading in m7 +3. **1.12.2 version leaf** — with core holding all game logic, mc1122 only needs to provide PlatformService implementation + version-specific entity/block/item/GUI code +4. **Data migration tooling** — NPC save format compatibility across versions