diff --git a/.AGENTS/CORE_ABSTRACTION.md b/.AGENTS/CORE_ABSTRACTION.md deleted file mode 100644 index 541c340a3..000000000 --- a/.AGENTS/CORE_ABSTRACTION.md +++ /dev/null @@ -1,56 +0,0 @@ -# Core Abstraction Reference - -Quick-reference for platform abstraction architecture and migration status. -For full details: `CORE_PLAN.md` (architecture), `CORE_MIGRATION_STATUS.md` (per-file blockers). - -## Module Layout - -``` -platform-api/ → Interfaces only (43 files). No MC imports. - ^ - core/ → Game logic (140 files). Imports platform-api only. - ^ -src/main/java/ → MC 1.7.10 implementations, wrappers, GUI, packets (~1,627 files) -``` - -## Migration Status: 183 / ~1,810 files abstracted - -### Fully Abstracted (in core/) -- **Controllers**: GlobalData, ServerTagMap, Transport, Faction, Magic, Tag, CategoryManager, APIRegistry -- **Data clusters**: Transport, Faction, Magic/MagicCycle/MagicEntry, Tag/TagMap, Frame/FramePart -- **Player data fragments**: PlayerDialogData, PlayerTransportData, PlayerEffect, AbilityHotbarData -- **Display data**: DialogImage, DialogColorData, Lines/Line, SkinOverlay, HitboxData, TintData -- **Infrastructure**: NBTTags, NBT factory, CustomNPCsThreader, network enums, developer registry -- **Constants**: 40+ enums (EnumRoleType, EnumQuestType, EnumAnimation, etc.) -- **Utilities**: ValueUtil, LRUHashMap, CacheHashMap, TextSplitter, FileNameHelper - -### Tier 1 — Blocked by IStack/Inventory Abstraction -Bank, BankController, AuctionClaim, AuctionListing, AuctionBlacklist, LinkedItem, RecipeAnvil, PlayerItemGiverData - -### Tier 2 — Blocked by IUser (EntityPlayer) Abstraction -Availability, FactionOptions, Dialog/DialogOption/DialogCategory, Quest/QuestCategory/QuestData, -CustomEffect, Party, PlayerData, PlayerFactionData, all remaining Player*Data classes - -### Tier 3 — Blocked by Entity/World Abstraction (IMob, IGameWorld) -SpawnData, SpawnController, Animation, AnimationData, DataTransform, MarkData, TelegraphInstance - -### Tier 4 — Script System (DO NOT TOUCH) -All I*Script* interfaces, ScriptHandler, ScriptContainer, AbilityScript, EffectScript, Action framework - -### Tier 5 — Heavy MC Coupling (Long-term) -RecipeCarpentry, RecipeController, Ability.java + all ability types, ChunkController, ProfileController, SyncController - -## Key Rules - -- **Interfaces**: Short `I` prefix (`IMob`, `IUser`, `IStack`). No `Platform` prefix. Access: `PlatformServiceHolder.get()` -- **Core imports**: Only `java.*`, platform-api interfaces, other core classes — never MC -- **NBT**: `NBT.compound()` / `NBT.list()`. File I/O via `PlatformServiceHolder` -- **Shadow pattern**: Core + mc1710 share packages. mc1710 adds `implements IFaction`, SyncController calls, MC-type methods - -## Recommended Migration Order - -1. mc1710 shadow files for already-migrated controllers -2. `IUser` implementation (unblocks Tier 2: ~15 files) -3. `IStack` / inventory abstraction (unblocks Tier 1: ~8 files) -4. Dialog cluster → Quest cluster → Player data classes -5. `NBTJsonUtil` to core (unblocks Dialog/Quest controllers) diff --git a/.AGENTS/FORBIDDEN_PRACTICES.md b/.AGENTS/FORBIDDEN_PRACTICES.md index 1d6d36f01..214309b97 100644 --- a/.AGENTS/FORBIDDEN_PRACTICES.md +++ b/.AGENTS/FORBIDDEN_PRACTICES.md @@ -1,7 +1,7 @@ # Forbidden Practices — CustomNPC-Plus Quick-reference guardrails. Prevents regressions, guides contributors. -See also: `AGENTS.md` (architecture), `CORE_PLAN.md` (roadmap), `CORE_MIGRATION_STATUS.md` (blockers). +See also: `AGENTS.md` (architecture), `SESSION_MEMORY.md` (roadmap). --- @@ -11,51 +11,30 @@ See also: `AGENTS.md` (architecture), `CORE_PLAN.md` (roadmap), `CORE_MIGRATION_ - **NEVER use mutable static fields for shared state.** Known violation: `RandomPositionGeneratorAlt.staticVector` — a mutable `Vec3` reused across calls. Do not replicate this pattern. ### Core / Platform-API Isolation -- **NEVER import MC classes in `core/` or `platform-api/`.** Use platform interfaces only (`INBTCompound`, `IUser`, `IStack`, `IGameWorld`). +- **NEVER import MC classes in `core/` or `platform-api/`.** Use the existing platform-api interfaces (`INbt`, `IPlayer`, `IItemStack`, `IWorld`, `IEntity`, `ICustomNpc`, etc.). - **NEVER import wrapper classes in `core/`.** Only interfaces from `platform-api/`. - **NEVER call `getMCNBT()` / `getMCTagList()` from `core/` code.** These are escape hatches on `INbt`/`INbtList` for mc1710 code only. - **NEVER use `new NBTTagCompound()` in `core/`.** Use `NBT.compound()` / `NBT.list()`. - **NEVER use `CompressedStreamTools` in `core/`.** Use `PlatformServiceHolder.get().readCompressedNBT()`. - **NEVER use `LogWriter` in `core/`.** Use `PlatformServiceHolder.get().logError()`. +- **NEVER create semantically duplicate interfaces.** Use the real interfaces from `platform-api/` (`IPlayer`, `IItemStack`, `IWorld`, `IEntity`, `ICustomNpc`, `INbt`, etc.). Do NOT invent new names like `IUser`, `IStack`, `IGameWorld` — those don't exist and never should. ### Split-Package Contract - **NEVER break the split-package shadow.** When a class exists in both `core/` and `src/main/java/` with the same package, mc1710 shadows core at compile time. The mc1710 version adds `implements IFaction`, SyncController calls, MC-specific methods. Core version must remain MC-free. ### Naming -- **Platform interfaces:** Short `I` prefix, no `Platform` in name. `IUser` not `IPlatformUser`. +- **Platform interfaces:** Use the scripting API interface names as-is (`IPlayer`, `IEntity`, `IItemStack`, `IWorld`, `ICustomNpc`). These are being merged into platform-api from the scripting API. Do NOT create new names. - **MC1710 wrappers:** `[Thing]Wrapper`. No `MC1710` prefix. `PlayerWrapper` not `MC1710PlayerWrapper`. -- **Scripting API** (`IPlayer`, `IEntity`, `ICustomNpc`) is a separate concern from platform interfaces. Different package, different purpose. Do not conflate. +- **Scripting API** (`IPlayer`, `IEntity`, `ICustomNpc`) is being merged into `platform-api/` — same package (`noppes.npcs.api.*`), stripped of MC type parameters. MC-free versions live in platform-api, version-specific extensions shadow in each mc*/ leaf. + +### Per-Version Code (DO NOT ABSTRACT) +- **NEVER abstract mixins** (`noppes.npcs.mixin`). Leave the current 1.7.10 mixins as-is. Each version leaf will have its own version-specific mixins. +- **NEVER abstract addon classes** (`kamkeel.npcs.addon`). These are per-version integrations. Leave 1.7.10 addons as-is. New version implementations will be created separately after migration. +- **NEVER abstract `BucketUtil` or `VaultUtil`**. These are per-version utility classes. Leave the 1.7.10 versions as-is. Each version leaf gets its own implementation. --- -## 2. Deprecated Components - -| Component | Status | Replacement | -|---|---|---| -| `CommandNoppes` (`foxz.command`) | Deprecated | Use `/kam` command hierarchy (`kamkeel.npcs.command.CommandKamkeel`) | -| `GuiScriptInterface.saveText()` | Deprecated | Use current script save mechanism | -| `NBTTags.GetScript` / `GetScriptOld` / `NBTScript` | mc1710-only | Not migrated to core; uses `IScriptHandler` directly | -| `NBTTags.getItemStackList/Array` | mc1710-only | Uses `NoppesUtilServer.readItem()` + `ItemStack`; no core equivalent yet | - ---- - -## 3. Forbidden Subsystem Areas (for Core Migration) - -Do NOT attempt to migrate these to `core/`. See `CORE_PLAN.md` §DO NOT TOUCH. - -| Subsystem | Reason | Tier | -|---|---|---| -| **Script system** — `ScriptHandler`, `ScriptContainer`, `I*Script*`, Action framework | Deeply coupled, not yet planned | 4 | -| **Ability.java** + ability type classes | 30+ MC imports (Block, Entity, DamageSource, Vec3, World) | 5 | -| **Entity classes** — `EntityNPCInterface`, `EntityCustomNpc`, all `EntityAbility*` | Extend MC `Entity` directly | 5 | -| **Recipe system** — `RecipeCarpentry`, `RecipeController` | Extends `ShapedRecipes`, uses `CraftingManager` | 5 | -| **Chunk system** — `ChunkController` | `ForgeChunkManager` dependency | 5 | -| **SyncController** | ByteBuf, packets, Minecraft server | 5 | -| **Profile system** — `ProfileController` | EntityPlayer lifecycle, Mojang API | 5 | - ---- - -## 4. Architectural Guardrails +## 2. Architectural Guardrails ### Dependency Flow ``` @@ -66,21 +45,3 @@ platform-api/ (interfaces only, zero MC deps) src/main/java/ (mc1710: wrappers, entities, GUI, packets) ``` Violations = build failures. Core depends on platform-api only. - -### mc1710 Shadow Responsibilities -When a controller is migrated to `core/`, the mc1710 shadow file MUST: -1. Add `implements IFactionHandler` (or equivalent scripting API interface) -2. Re-add `SyncController` calls in save/delete methods -3. Re-add `EntityPlayer`/`IPlayer` overload methods -4. Override MC-dependent factory methods (e.g., `createDefaults()` for ItemStack) - -### NBT Serialization -- Core: `readNBT(INBTCompound)` / `writeNBT(INBTCompound)` — interfaces only -- mc1710: can use `NBTTagCompound` directly, cast via `getMCNBT()` at boundary - -### File I/O in Core -- `CustomNpcs.getWorldSaveDirectory()` → `PlatformServiceHolder.get().getWorldSaveDirectory()` -- Async saves use `CustomNPCsThreader` thread pool (already in core) - -### What Stays mc1710-Only (permanently) -GUI/rendering (`@SideOnly`), packets/network (ByteBuf), `FieldDef`/ability GUI, `GameRegistry`, `ForgeChunkManager`, `WeightedRandom`, scripting API interface implementations. diff --git a/.AGENTS/MIGRATION_RESEARCH.md b/.AGENTS/MIGRATION_RESEARCH.md new file mode 100644 index 000000000..fd86c9d5e --- /dev/null +++ b/.AGENTS/MIGRATION_RESEARCH.md @@ -0,0 +1,271 @@ + +**Related documents:** +- `MIGRATION_ROADMAP.md` — Phased migration plan with milestones +- `MULTI_VERSION_RESEARCH.md` — Detailed external research (tools, repos, real implementations) +- `MC_COUPLING_ANALYSIS.md` — Quantified MC-dependency breakdown by subsystem +- `BUILD_SYSTEM.md` — Gradle architecture, version-specific build requirements +- `SCRIPTING_TOOLCHAIN.md` — Java → TypeScript → Editor pipeline + +--- + + +## Owner's Vision + +**Goal:** Port CustomNPC-Plus from 1.7.10 to **1.12.2, 1.16.5, and 1.20.1 simultaneously**. + +**Key Constraints (from owner):** +- **NOT sequential** — refuses to spend 2-3 months per version one at a time +- Must tackle all versions at once, to the highest possible degree +- 1.7.10 remains the primary/active build during porting +- Time and budget are limited — efficiency is paramount + +--- + +## Current State Assessment + +### Abstraction Progress +- **183 / ~1,810 files abstracted** (~10%) into `core/` + `platform-api/` +- `platform-api/`: 48 interface files (NBT, entity wrapping, file I/O, logging, scheduling) +- `core/`: 140 files (8 controllers, 60+ data classes, enums, utils) +- `PlatformService` exists but is used in <0.2% of MC-dependent code + +### MC-Dependent Code Distribution (~1,424 files import net.minecraft.*) + +| Subsystem | File Count | Coupling Level | Porting Difficulty | +|---|---|---|---| +| **GUI/Client/Rendering** | 212 | VERSION-LOCKED | Extreme — rewrite per version | +| **Networking/Packets** | 100+ | HEAVY-MC | High — framework changes every version | +| **Blocks + Tiles** | 97 | VERSION-LOCKED | High — Flattening breaks everything | +| **Controllers/Data** | 81 | LIGHT-MC | Medium — mostly NBT + EntityPlayer params | +| **Scripting Wrappers** | 50+ | HEAVY-MC | Medium — API surface stable-ish | +| **Abilities** | 44 | HEAVY-MC | High — DO NOT TOUCH yet | +| **Items** | 41 | LIGHT-MC | Medium — registration centralized in CustomItems.java | +| **AI** | 29 | HEAVY-MC | Medium — EntityAI API changes significantly | +| **Commands** | 22 | VERSION-LOCKED | Medium — Brigadier in 1.13+ | +| **Roles/Jobs** | 19 | LIGHT-MC | Low — mostly game logic with entity params | +| **Config** | 9 | LIGHT-MC | Low — Forge config API changes but logic same | + +### 1.7.10 → 1.12.2 API Differences (Verified Against This Codebase) + +| Pattern | Change Level | Files Affected | Details | +|---|---|---|---| +| FML package (cpw.mods.fml → net.minecraftforge.fml) | MINOR_CHANGE | 524 files | Mass rename, mechanical | +| Entity registration | MINOR_CHANGE | 1 file (CustomNpcs.java) | Signature change (added tracking params) | +| Event system (@SubscribeEvent, EVENT_BUS) | IDENTICAL | 16+ files | Same API | +| GUI handler (NetworkRegistry) | IDENTICAL | 1 file | Same API | +| NBT (NBTTagCompound) | IDENTICAL | Hundreds | Same API | +| World save data (WorldSavedData) | IDENTICAL | Several | Same API | +| @Mod, @EventHandler, @SidedProxy | MINOR_CHANGE | ~5 files | Package rename | +| **ItemStack null→EMPTY** (1.11+) | **BREAKING_CHANGE** | **37+ null checks, 390+ files ref ItemStack** | **stack==null must become stack.isEmpty(). MASSIVE — the plan originally missed this entirely** | +| Packet system (SimpleNetworkWrapper) | BREAKING_CHANGE | 100+ files | Becomes SimpleChannel | +| IInventory → IItemHandler (Capabilities) | BREAKING_CHANGE | 59+ files | New capability system alongside old | +| Block/Item registration (GameRegistry) | BREAKING_CHANGE | 18 files (62 calls in CustomItems.java) | Deprecated in 1.12; must use RegistryEvent.Register | +| **World.getBlock → getBlockState** | BREAKING_CHANGE | 59+ files | Block metadata → IBlockState system | +| **getUnlocalizedName → getTranslationKey** | BREAKING_CHANGE | 59+ files | Deprecated in 1.11+ | + +> **⚠️ CORRECTION (2026-03-15):** The previous version of this table listed GameRegistry as "IDENTICAL" and was missing ItemStack nullability, getBlockState, and getTranslationKey changes entirely. The 1.12.2 port is NOT 95% mechanical — it's ~60-70% mechanical (the 524 renames are real), with 30-40% requiring real code changes that will cause crashes if missed. + +--- + +## Critical Research Findings + +### The Hard Truth: Nobody Has Done This Before + +**No Minecraft mod in existence successfully shares code between 1.7.10 and modern (1.16+) versions.** Exhaustive GitHub search confirmed: + +| Pattern | Example | Lowest MC Version | Shared Code? | +|---|---|---|---| +| Preprocessor multi-version | Polyfrost/OneConfig (280★) | **1.8.9** (not 1.7.10) | Yes, via `#if MC>=` | +| Multi-module per-loader | JEI (Core/Common/NeoForge/Fabric) | Per-branch only | Yes, within one version | +| Branch-per-version | Applied Energistics 2 | 1.15+ (no 1.7.10 branch) | No — independent codebases | +| Separate repos | GregTechCEu (1.12) + GT-Modern (1.20) | 1.12 / 1.20 separately | No — complete rewrites | +| 1.7.10 only | GTNH ecosystem (93 repos) | 1.7.10 | N/A | + +**CustomNPC-Plus's platform-api/core approach is genuinely novel** — it's the JEI Core/Common pattern applied retroactively to 1.7.10, which nobody else has attempted. + +### Build System: Composite Builds, NOT Separate Wrappers + +Oracle recommended separate Gradle wrappers. **This is wrong.** Evidence from real implementations: + +| Tool | What It Does | Status | +|---|---|---| +| **Gradle Composite Builds** (`includeBuild`) | Each version is an independent build with its own plugin classpath | VERIFIED — only stable way to mix RFG + FG | +| **Gradle Toolchains** | Run Gradle on JDK 21, compile with JDK 8 or 17 per subproject | VERIFIED — standard Gradle feature | +| **ModStitch** (github.com/isXander/modstitch) | Unifies RFG + ForgeGradle + NeoGradle in one build | **UNVERIFIED** — RFG support is still an unmerged PR (#42). Do not rely on this. | +| **ReplayMod Preprocessor** | `#if MC>=` directives in Java comments | VERIFIED — works, but build tooling doesn't support 1.7.10 via Loom | +| **Essential Gradle Toolkit** | Wraps preprocessor with cleaner DSL | VERIFIED — plugin `gg.essential.multi-version` v0.6.7 | +| **Deftu multiversion** | Production multi-version plugin (used by OneConfig) | VERIFIED — `dev.deftu.gradle.multiversion-root` v2.73.0 | + +**Key constraint:** RFG and ForgeGradle/NeoGradle CANNOT share a Gradle classpath in multi-project builds. Composite builds (`includeBuild`) are required. + +### Preprocessor Limitations for 1.7.10 + +The ReplayMod preprocessor **syntax** supports 1.7.10 (version `10710`). But: +- The **build tooling** (Architectury Loom, Essential Loom) does NOT support 1.7.10 +- ReplayMod itself dropped 1.7.10 support when moving to Gradle 7 +- The preprocessor is a text tool — it works on any Java file regardless of MC version +- **For CustomNPC-Plus:** The preprocessor could process source files for 1.7.10 IF combined with RetroFuturaGradle (not Loom). This needs prototyping. + +--- + +## Corrected Architecture (Post-Critical-Review) + +### Oracle's Recommendation vs Evidence-Based Correction + +| Aspect | Oracle Said | Evidence Says | Decision | +|---|---|---|---| +| Build system | Separate Gradle wrappers per leaf | Composite builds + single wrapper | **Composite builds** | +| Layer count | 6 layers (platform-api → core → legacy-common → modern-common → leaves) | Preprocessor can replace family-common layers | **5 layers with optional preprocessor in version leaves** | +| legacy-common / modern-common | Dedicated modules | ~100+ files could go here, BUT preprocessor handles syntactic diffs | **Start without them; add only if code duplication proves >50 files** | +| 1.7.10→1.12.2 gap | Treated as equivalent to other gaps | Easier than 1.16+ but NOT trivial — 524 renames + 5 breaking changes (ItemStack null→EMPTY, IInventory, getBlockState, getTranslationKey, GameRegistry events) | **1.12.2 is ~60-70% mechanical, 30-40% real code changes** | + +### Recommended Project Structure + +``` +CustomNPC-Plus/ + platform-api/ → Plain Java 8 library (interfaces) — SHARED BY ALL + core/ → Plain Java 8 library (game logic) — SHARED BY ALL + mc1710/ → Current src/main/java/ (RetroFuturaGradle) — COMPOSITE BUILD + mc1122/ → 1.12.2 (RetroFuturaGradle — yes, RFG handles 1.12.2) — COMPOSITE BUILD + mc1165/ → 1.16.5 (ForgeGradle 6) — COMPOSITE BUILD + mc1201/ → 1.20.1 (NeoGradle/ModDevGradle 2) — COMPOSITE BUILD + gradle-plugins/ → TypeScript .d.ts generator (unchanged) +``` + +**Why no legacy-common/modern-common initially:** +- The preprocessor can handle syntactic differences within version leaves +- Most LIGHT-MC code should be migrated to `core/` with platform interfaces instead of duplicated in a family-common layer +- If >50 files of genuine version-family-specific code emerges during porting, THEN add the intermediate layers +- Simpler architecture = less overhead = faster iteration + +### Build System Architecture + +``` +Root settings.gradle: + include 'platform-api', 'core' → Plain Java libraries (multi-project) + includeBuild 'mc1710' → Composite build (RetroFuturaGradle) + includeBuild 'mc1122' → Composite build (RetroFuturaGradle) + includeBuild 'mc1165' → Composite build (ForgeGradle 6) + includeBuild 'mc1201' → Composite build (NeoGradle) + includeBuild 'gradle-plugins' → Already composite + +Each mc*/ has its own: + settings.gradle → Declares dependency on root platform-api/core via includeBuild '..' + build.gradle → Applies version-specific Gradle plugin + gradle.properties → MC version, Forge version, mappings + src/main/java/ → Version-specific implementations +``` + +**Gradle Toolchains** handle JDK differences (8 for legacy, 17 for 1.20.1). + +--- + +## Revised Abstraction Order (Maximum Parallelism) + +The key insight: **1.12.2 is significantly closer to 1.7.10 than 1.16.5+, but it is NOT trivial.** Beyond the 524 mechanical renames, there are 5 breaking API changes affecting 200+ files total. Still, it is the easiest version jump and should be tackled first. + +### Track A: Core Abstraction (enables ALL versions) +1. Finish mc1710 shadow files for migrated controllers +2. Expand `IPlayer` / `IItemStack` / `IWorld` usage in core (use the real platform-api interfaces — DO NOT create duplicates) +3. Dialog cluster → Quest cluster → PlayerData migration to core +4. Packet DTO abstraction in core +5. Command abstraction in core + +### Track B: 1.12.2 Port (CAN START IMMEDIATELY — easier than 1.16+ but NOT trivial) +1. Copy mc1710/ → mc1122/ +2. Mass-rename cpw.mods.fml → net.minecraftforge.fml (524 files, mechanical) +3. **Replace all ItemStack null checks with isEmpty()** (37+ files with null checks, 390+ files reference ItemStack — the BIGGEST hidden change) +4. Update block/item registration to RegistryEvent pattern (18 files, 62 calls in CustomItems.java) +5. Update entity registration signature (1 file) +6. Replace getUnlocalizedName → getTranslationKey (59+ files) +7. Address World.getBlock → getBlockState usage (59+ files) +8. Refactor packet system (SimpleNetworkWrapper → SimpleChannel — structural rewrite) +9. Begin IInventory → IItemHandler migration for containers (59+ files, can be incremental) +10. Set up RetroFuturaGradle for 1.12.2 (confirmed: RFG supports 1.12.2) +11. Test and iterate + +### Track C: 1.16.5 Port (start after Track A Phase 1-3) +1. Create mc1165/ with ForgeGradle 6 +2. Implement PlatformService for 1.16.5 +3. Port core controllers (they just work — MC-free) +4. Port networking (new packet system) +5. Port commands (Brigadier adapter) +6. Port blocks (BlockState — the Flattening work) +7. Port essential admin GUIs (rewrite, not port) + +### Track D: 1.20.1 Port (start after Track C is 50% done) +1. Create mc1201/ based on mc1165/ (close enough) +2. Implement PlatformService for 1.20.1 +3. Adapt for NeoForge API differences +4. Mostly rides on 1.16.5 work + +**Tracks A and B can run in parallel immediately.** Track C starts when core interfaces exist. Track D is incremental from C. + +--- + +## MVP Targets Per Version + +### 1.7.10 — Full Primary (unchanged) +All features, full parity. This is the production build. + +### 1.12.2 — "Bridge Build" (Closest to 1.7.10, but has real breaking changes) +- NPC spawn, persist, despawn lifecycle +- Dialog system, Quest system, Faction system +- Core networking (NPC sync, player data) +- Basic AI + combat +- Essential editor/admin GUIs +- Commands (`/kam` hierarchy) +- **NOT initially:** Abilities, auction, animation maker, scripting IDE + +### 1.16.5 — "NPC Core" Modern +- Same feature set as 1.12.2 MVP +- Server-first: commands and admin workflows before full GUI +- Basic NPC editor screen +- **NOT initially:** Full GUI suite, abilities, auction, custom models + +### 1.20.1 — "NPC Core" Latest +- Same as 1.16.5 — incremental from it +- Client polish lags behind server feature parity + +--- + +## Critical Warnings + +1. **You're the first to do this** — no existing mod shares code between 1.7.10 and modern. Expect uncharted territory. +2. **Don't mirror Minecraft class-for-class in platform-api** — keep interfaces coarse and purpose-driven +3. **Don't promise full GUI parity on modern versions first** — 212 files, completely different per version, do LAST +4. **Don't let preprocessor guards spread into core/** — only in version-leaf code +5. **1.12.2 is easier than 1.16+ but NOT trivial** — 524 mechanical renames + 5 breaking changes (ItemStack null→EMPTY, IInventory, getBlockState, getTranslationKey, GameRegistry events) affecting 200+ files +6. **Composite builds, not separate wrappers** — one Gradle wrapper, `includeBuild` per version leaf +7. **API merge is a phased operation** — move MC-free interfaces first (~131), then strip MC imports from the remaining 71. Don't try to move everything in one shot. + +--- + +## Open Questions / Future Decisions + +1. Can the ReplayMod preprocessor be made to work with RetroFuturaGradle (instead of Loom)? Needs prototyping. +2. Should version leaves share a single `build.gradle.kts` via the preprocessor's pattern (all versions point to `../../build.gradle.kts`)? Or keep independent build files? +3. Scripting API compatibility — can the same `.js`/`.java` scripts work across versions? +4. Addon compatibility — DBC Addon, Gecko Addon, AW Addon need version-specific builds +5. Data format compatibility — can NPC save files from 1.7.10 load on 1.20.1? +6. When to add `legacy-common/` and `modern-common/` layers — set threshold at >50 duplicated files + +--- + +## Research Agent Summary (12 agents deployed) + +| Agent | Type | Key Finding | +|---|---|---| +| explore #1 | MC-dependent code | 1,424 files import net.minecraft.*, GUI is biggest hotspot (212 files) | +| explore #2 | Build system | Single-version locked, GTNH Convention + RFG | +| explore #3 | Subsystem coupling | Controllers/data are LIGHT-MC, AI/networking are HEAVY-MC | +| explore #4 | 1.7.10→1.12.2 API diff | 95% identical, only packets break, 524 files need package rename | +| explore #5 | legacy-common validation | ~100+ files use pre-Flattening patterns (metadata, IInventory) | +| librarian #1 | Porting strategies | Architectury 1.16.5+ only, preprocessor for syntactic diffs | +| librarian #2 | Real multi-version repos | Essential Mod gold standard, modstitch bridges RFG+FG, Loom consumes plain Java libs | +| librarian #3 | ForgeGradle matrix | RFG handles 1.7.10+1.12.2, FG6 for 1.16.5, ModDevGradle for 1.20.1, composite builds required | +| unspecified-high #1 | Preprocessor research | ReplayMod preprocessor syntax supports 1.7.10 (10710), but Loom doesn't; Essential wraps it | +| unspecified-high #2 | Real multi-version mods | **Nobody shares code between 1.7.10 and modern** — CustomNPC+ approach is genuinely novel | +| unspecified-high #3 | Write MULTI_VERSION_RESEARCH.md | Compiled all external research to permanent doc | +| unspecified-high #4 | Write MC_COUPLING_ANALYSIS.md | Compiled all coupling data to permanent doc | +| Oracle | Architecture strategy | Two-family monorepo (partially overridden by evidence) | \ No newline at end of file diff --git a/.AGENTS/MIGRATION_ROADMAP.md b/.AGENTS/MIGRATION_ROADMAP.md new file mode 100644 index 000000000..92e65270c --- /dev/null +++ b/.AGENTS/MIGRATION_ROADMAP.md @@ -0,0 +1,263 @@ +## Migration Roadmap (Added 2026-03-15 — Post-Critical-Review) + +### Overview + +This roadmap is organized into **4 phases** with **parallel tracks** where possible. Each phase has concrete milestones, estimated scope, dependencies, and a verification strategy. + +**Key principle:** Maximize code sharing early (platform-api + core), then build version leaves on top. The more code that lives in platform-api/core before starting version leaves, the less per-version work there is. + +``` +Timeline (approximate): +Phase 0 ████░░░░░░░░░░░░░░░░ Foundation (API merge + build system) +Phase 1 ░░░░████████░░░░░░░░ Core expansion + 1.12.2 leaf +Phase 2 ░░░░░░░░░░░░████████ 1.16.5 + 1.20.1 leaves +Phase 3 ░░░░░░░░░░░░░░░░████ Feature parity + polish +``` + +--- + +### Phase 0: Foundation (Prerequisites for everything else) + +**Goal:** Get the build system working for multi-version and merge the scripting API into platform-api. + +#### 0A. Composite Build Setup +- [ ] Create `mc1710/` directory, move current `src/main/java/` and `src/main/resources/` into it +- [ ] Create `mc1710/settings.gradle` and `mc1710/build.gradle` with RFG +- [ ] Update root `settings.gradle` to use `includeBuild 'mc1710'` instead of direct source +- [ ] Verify `mc1710/` builds and runs identically to current root build +- [ ] Verify `platform-api` and `core` are consumed correctly via composite build dependency + +**Scope:** ~5-10 files (build configs only). No Java changes. +**Risk:** Medium — build system restructure can surface classpath/dependency issues. +**Verification:** `./gradlew build` succeeds, `runClient` launches, existing tests pass. + +#### 0B. Scripting API → platform-api Merge (Phase 1 of API merge: MC-free interfaces) +- [ ] Identify the ~131 MC-free interfaces in `src/api/java/` (no `net.minecraft.*` or `cpw.mods.fml.*` imports) +- [ ] Move them into `platform-api/` retaining exact package structure (`noppes.npcs.api.*`) +- [ ] Reconcile the 30 existing split-package shadows (platform-api already has MC-free versions of these) +- [ ] Strip generic type parameters from 5 entity interfaces (`IEntity`, `IEntityLivingBase`, `IEntityLiving`, `ICustomNpc`, `IPlayer`) +- [ ] Update `core/` imports if any were pointing at the old location +- [ ] Update `mc1710/` to shadow the moved interfaces where MC-specific extensions are needed + +**Scope:** ~131 file moves + 30 reconciliations + 5 generics strips. +**Risk:** Low-Medium — package structure preserved, no behavioral changes. +**Verification:** `core/` compiles, `mc1710/` compiles, no new import errors. +**Dependency:** Phase 0A must be complete (mc1710 is a separate build). + +#### 0C. Scripting API → platform-api Merge (Phase 2: MC-contaminated interfaces) +- [ ] Identify 71 MC-contaminated interfaces in `src/api/java/` +- [ ] For each, replace MC type references with platform-api equivalents or Object returns +- [ ] Handle event interfaces: create platform `@Cancelable` annotation (or use the planned custom annotation parser) +- [ ] Refactor `AbstractNpcAPI` — split into MC-free interface in platform-api + mc1710 implementation class +- [ ] Move cleaned interfaces to `platform-api/` +- [ ] Drop the 5 vendored MC class stubs (`net/minecraft/` in api/) +- [ ] Update all `mc1710/` code importing these interfaces + +**Scope:** 71 files, each needs individual review and MC-stripping. +**Risk:** Medium-High — method signature changes ripple through 276 files in mc1710 that import the API (743 import sites). +**Verification:** Full `mc1710/` build succeeds, scripting engine tests pass. +**Dependency:** Phase 0B complete. + +#### 0D. Complete Existing Core TODOs (mc1710 shadow files) + +The previous core migration left 22 TODOs across 8 files — all are incomplete mc1710 shadow implementations that need to be created or finished: + +**Controllers needing mc1710 shadows (4 files, 11 TODOs):** +- [ ] `FactionController.java` — create mc1710 shadow that `implements IFactionHandler`, adds SyncController calls in save/delete +- [ ] `MagicController.java` — create mc1710 shadow that `implements IMagicHandler`, adds ItemStack resolution, SyncController calls in save/delete +- [ ] `TransportController.java` — create mc1710 shadow that `implements ITransportHandler` +- [ ] `TagController.java` — create mc1710 shadow that `implements ITagHandler` + +**Data classes needing mc1710 shadows (2 files, 5 TODOs):** +- [ ] `Faction.java` — create mc1710 shadow that `implements IFaction` +- [ ] `Magic.java` — create mc1710 shadow that `implements IMagic`, adds ItemStack field and GameRegistry resolution in readNBT/writeNBT + +**Utility needing mc1710 version (1 file, 4 TODOs):** +- [ ] `NBTTags.java` — mc1710 version needs: ItemStack list methods, nbtDoubleList (uses NBTTagDouble), Script methods (uses IScriptHandler/NBTTagCompound), getIntAt (uses NBTTagInt) + +**Data needing completion (1 file, 2 TODOs):** +- [ ] `PlayerEffect.java` — needs CustomEffectController integration + IPlayer callback mechanism + +**Scope:** 8 files with 22 TODOs. Creates ~6-8 new mc1710 shadow files + completes 2 existing stubs. +**Risk:** Low — these are well-understood patterns (split-package shadow). Each TODO explicitly describes what the mc1710 version must add. +**Verification:** Per file: mc1710 shadow compiles, controller loads/saves correctly, no regressions in NPC behavior. +**Dependency:** Can run in parallel with 0B/0C, or immediately. + +--- + +### Phase 1: Core Expansion + 1.12.2 Leaf (Parallel tracks) + +**Goal:** Migrate the bulk of game logic to core/ while simultaneously standing up the 1.12.2 version leaf. + +#### Track 1A: Core Controller Migration + +Now that subsystem restrictions are lifted, the migration order is by ROI: + +| Priority | Subsystem | Files | Blockers | Unlocks | +|---|---|---|---|---| +| 1 | Remaining Controllers/Data | ~35 unmigrated | Need `IPlayer`, `IItemStack` coverage expanded in platform-api | Quest, Dialog, PlayerData sharing | +| 2 | Roles/Jobs | 19 | Entity param abstraction via existing interfaces | Role/Job logic shared across versions | +| 3 | Items (logic only) | ~25 | `IItemStack` abstraction | Item behavior shared (registration stays per-version) | +| 4 | Quest system | ~10 | Dialog + PlayerData in core | Quest logic shared | +| 5 | Dialog system | ~8 | Controller/Data in core | Dialog logic shared | +| 6 | Script system (containers/hooks) | ~30 | ScriptContainer needs platform abstraction | Scripting behavior shared | +| 7 | Profile system | ~5 | `IPlayer` + PlayerData in core | Profile logic shared | +| 8 | Packet DTOs | ~50 | INetworkService in platform-api | Packet data shared (transport per-version) | +| 9 | Command abstraction | ~22 | ICommandService in platform-api | Command logic shared (dispatch per-version) | + +**New platform-api interfaces needed:** +- `INetworkService` — packet registration, sending, channel management +- `ICommandService` — command registration and dispatch +- `IRegistryService` — block/item/entity registration abstraction +- `IEventBus` — event subscription and dispatch abstraction +- Expand `IPlayer` and `IItemStack` coverage as needed by core migration (use the EXISTING interfaces — do NOT create duplicates) + +**Scope:** ~200 files migrated to core over this phase. +**Risk:** High — each controller migration can surface hidden MC dependencies. +**Verification:** Per-controller: core compiles, mc1710 shadow compiles, controller tests pass. + +#### Track 1B: 1.12.2 Version Leaf (parallel with 1A) + +- [ ] Create `mc1122/` directory structure with RFG build config +- [ ] Copy mc1710 source → mc1122 as starting point +- [ ] **Mechanical changes (can be scripted/automated):** + - Mass-rename `cpw.mods.fml` → `net.minecraftforge.fml` (524 files) + - Replace `getUnlocalizedName` → `getTranslationKey` (59+ files) +- [ ] **Breaking changes (require manual work):** + - ItemStack null→isEmpty(): audit and fix 37+ null-check sites, 390+ files that handle ItemStack + - GameRegistry → RegistryEvent.Register pattern (18 files, 62 calls) + - Entity registration signature update (1 file) + - World.getBlock → getBlockState adaptation (59+ files) + - SimpleNetworkWrapper → SimpleChannel packet rewrite (100+ files) + - IInventory → IItemHandler for containers (59+ files, can be incremental — IInventory still works in 1.12) +- [ ] Set up 1.12.2 Forge MDK mappings in `mc1122/gradle.properties` +- [ ] Build, fix compilation errors, iterate +- [ ] Test core NPC lifecycle: spawn, persist, despawn + +**Scope:** Full mc1710 codebase copy (~1,722 files) + modifications. +**Risk:** Medium — most changes are well-understood patterns, but the volume is large. +**Verification:** `mc1122/` builds, basic NPC spawns in 1.12.2 client, save/load works. +**Key insight:** IInventory still works in 1.12.2 (just deprecated), so container migration can be deferred. Focus on the 4 truly breaking items first: ItemStack null→EMPTY, GameRegistry events, packet system, entity registration. + +--- + +### Phase 2: Modern Version Leaves (1.16.5 + 1.20.1) + +**Goal:** Stand up 1.16.5 and 1.20.1 version leaves. These benefit from all the core/ work done in Phase 1. + +**Dependency:** Phase 1A should be at least 50% complete (controllers, data, roles/jobs in core). + +#### Track 2A: 1.16.5 Version Leaf + +- [ ] Create `mc1165/` with ForgeGradle 6 build config +- [ ] Implement `PlatformService` for 1.16.5 (MC type wrappers, NBT, file I/O) +- [ ] Core controllers work automatically — they depend only on platform-api +- [ ] Port networking (entirely new packet system in 1.16) +- [ ] Port commands (Brigadier adapter — command tree maps conceptually) +- [ ] Port blocks (BlockState — the Flattening. Metadata → block properties. DeferredRegister for registration) +- [ ] Port items (DeferredRegister, no metadata) +- [ ] Port AI (EntityAI → Goal system) +- [ ] Port essential admin GUIs: NPC editor, Quest editor, Dialog editor (rewrite, not port — Screen/Button/MatrixStack API) +- [ ] Port entity registration (DeferredRegister + EntityType.Builder) + +**Scope:** ~800-1000 files (version-specific implementations of what core doesn't cover). +**Risk:** High — this is the biggest version gap (1.7.10 → post-Flattening). Every block, item, entity, and GUI changes. +**Verification:** NPC spawns, basic dialog works, quests work, save/load works. + +#### Track 2B: 1.20.1 Version Leaf (start when 2A is ~50% done) + +- [ ] Create `mc1201/` based on `mc1165/` (1.16.5 → 1.20.1 is much smaller than 1.7.10 → 1.16.5) +- [ ] Implement `PlatformService` for 1.20.1 +- [ ] Adapt for NeoForge API differences (1.20.1 is the Forge→NeoForge transition) +- [ ] Update rendering (GuiGraphics wrapper, component-based text) +- [ ] Update registration patterns (NeoForge DeferredRegister differences) + +**Scope:** ~200-400 files of delta from 1.16.5. +**Risk:** Medium — incremental from 1.16.5, mostly API surface changes. +**Verification:** Same as 1.16.5 milestones. + +--- + +### Phase 3: Feature Parity + Polish + +**Goal:** Bring all version leaves to MVP feature parity, then expand. + +#### Per-version MVP checklist: +- [ ] NPC lifecycle (spawn, persist, despawn, AI, combat) +- [ ] Dialog system (create, edit, trigger, branching) +- [ ] Quest system (all quest types, tracking, rewards) +- [ ] Faction system (points, NPC reactions, conditions) +- [ ] Networking (NPC sync, player data, editor packets) +- [ ] Commands (`/kam` hierarchy, all subcommands) +- [ ] Essential GUIs (NPC editor, Quest editor, Dialog editor, Cloner) +- [ ] Config system +- [ ] Basic scripting (JS engine, script hooks for NPC/Player) + +#### Post-MVP (per version, prioritized): +1. Full scripting engine + script editor GUI +2. Ability system (entity types, energy system, telegraph) +3. Animation system +4. Auction/Economy system +5. Profile system +6. Full GUI suite (all editor screens, HUD, overlays) +7. Custom models / addon compatibility (Gecko, AW, DBC) + +--- + +### Risk Register + +| Risk | Likelihood | Impact | Mitigation | +|---|---|---|---| +| API merge breaks addon mods | High | High | Coordinate with addon authors. Ship platform-api as Maven artifact. Provide migration guide. | +| ItemStack null→EMPTY changes cause subtle runtime bugs | High | Medium | Automated grep + manual audit. Write a test suite for ItemStack handling. | +| Build system complexity (4 Gradle plugins, composite builds) | Medium | High | Get Phase 0A working and stable BEFORE any Java changes. Document build setup. | +| Core migration surfaces hidden MC dependencies in "LIGHT-MC" code | Medium | Medium | Migrate one controller at a time. Verify compilation after each. | +| 1.16.5 port takes much longer than estimated (Flattening impact) | High | High | Start with server-only (commands + data), defer GUI. Track 2B (1.20.1) doesn't start until 2A proves the pattern. | +| Preprocessor+RFG integration doesn't work | Medium | Low | Preprocessor is optional. The platform-api/core/leaf architecture works without it. | +| Script API behavior differences across MC versions | Medium | Medium | Define a compatibility spec: which script APIs are guaranteed cross-version vs. version-specific. | + +--- + +### Milestone Summary + +| Milestone | Phase | Deliverable | Success Criteria | +|---|---|---|---| +| **M0: Multi-build compiles** | 0A | mc1710/ as composite build | `./gradlew build` works, runClient launches | +| **M0.5: Core TODOs complete** | 0D | All 22 TODOs in core/ resolved, mc1710 shadows created | All 8 files have no remaining TODOs, mc1710 compiles, controllers save/load correctly | +| **M1: API in platform-api** | 0B+0C | All 202 API interfaces in platform-api | core/ and mc1710/ compile, no MC imports in platform-api | +| **M2: Core 50%** | 1A | Controllers, data, roles, items in core | ~200 files in core, mc1710 shadows compile | +| **M3: 1.12.2 compiles** | 1B | mc1122/ builds successfully | Gradle build succeeds | +| **M4: 1.12.2 NPC spawns** | 1B | Basic NPC lifecycle on 1.12.2 | NPC spawns, persists, loads, has AI | +| **M5: 1.16.5 compiles** | 2A | mc1165/ builds successfully | Gradle build succeeds | +| **M6: 1.16.5 NPC spawns** | 2A | Basic NPC lifecycle on 1.16.5 | NPC spawns, persists, loads, has AI | +| **M7: 1.20.1 compiles** | 2B | mc1201/ builds successfully | Gradle build succeeds | +| **M8: All versions MVP** | 3 | NPC + Dialog + Quest + Faction on all versions | Full MVP checklist passes on each | + +--- + +### What This Roadmap Does NOT Cover (Future Planning Needed) + +1. **Addon porting strategy** — DBC, Gecko, AW addons each need version-specific builds. Requires separate planning. +2. **Data migration** — Can NPC save files from 1.7.10 load on 1.20.1? Needs a data format compatibility analysis. +3. **CI/CD** — Automated builds for all 4 versions, artifact publishing, test matrix. +4. **Scripting compatibility spec** — Which script APIs are guaranteed cross-version. +5. **Client-side scripting** — The client script system has version-specific rendering hooks. Needs per-version analysis. +6. **Performance testing** — Core abstraction layer adds indirection. Measure overhead on large NPC populations. + +**USER REVIEW FOR WHATS UNCOVERED** +1) Addon porting shouldn't be handled on CNPC+ side, but on addon side. Skip +2) Data migration is ESSENTIAL. Must be fleshed out ASAP. +3) Multi-version builds are also ESSENTIAL. One of the first things that must be tackled (paralelly while working on the refactor) +4) Handle this after migration +5) There is no client script system, but if you see one just migrate it as is. This will be handled after the migration +6) This too is after migration +--- + +## Critical Review Agent Summary (Session 2 — 2026-03-15, 4 agents deployed) + +| Agent | Type | Key Finding | +|---|---|---| +| unspecified-high #1 | Verify abstraction state | 188 files abstracted (claim ~correct). PlatformService adoption near-zero in mc1710 (1 file). ~50 files are trivial enums. NBT abstraction pattern works well. | +| unspecified-high #2 | Assess API merge feasibility | 202 API files total. 71 MC-contaminated. 30 naming conflicts (split-package shadow). 5 generics to strip. 743 import sites in mc1710. Move is feasible in phases. | +| librarian #1 | Validate build system claims | RFG 1.12.2 VERIFIED. Composite builds VERIFIED. ModStitch UNVERIFIED (PR not merged). Essential single-wrapper VERIFIED. Java toolchains VERIFIED. | +| explore #1 | Verify 1.12.2 mechanical port claim | "95% mechanical" is WRONG. Found 5 breaking changes plan missed: ItemStack null→EMPTY (37+ files), IInventory (59+), getBlockState (59+), getTranslationKey (59+), GameRegistry events (18). Corrected to ~60-70% mechanical. | diff --git a/.AGENTS/MULTI_VERSION_RESEARCH.md b/.AGENTS/MULTI_VERSION_RESEARCH.md index 724ad1518..52aae8fbe 100644 --- a/.AGENTS/MULTI_VERSION_RESEARCH.md +++ b/.AGENTS/MULTI_VERSION_RESEARCH.md @@ -130,7 +130,7 @@ platform-api → core → common (with preprocessor) → version leaves | Layer | Contents | MC Dependencies | |---|---|---| -| `platform-api/` | Interfaces only (`IUser`, `INBTCompound`, `PlatformService`) | None | +| `platform-api/` | Interfaces only (`IPlayer`, `INbt`, `PlatformService`) | None | | `core/` | MC-free game logic (controllers, data classes, enums, utils) | None | | `common/` | Shared MC-aware code with `#if` preprocessor directives | Yes (version-gated) | | `versions//` | Entity registration, rendering, version-specific implementations | Full MC + Forge/NeoForge | diff --git a/.AGENTS/SESSION_MEMORY.md b/.AGENTS/SESSION_MEMORY.md index fa2237e54..63cecb410 100644 --- a/.AGENTS/SESSION_MEMORY.md +++ b/.AGENTS/SESSION_MEMORY.md @@ -1,3 +1,89 @@ +________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________ +CURRENT USER PROMPT: + +## 1) MINECRAFT/FORGE PLATFORM ABSTRACTION: + +### package: platform-api/ +- Context: Before the migration plan, this was previously (and currently, we only just started migrating) just used for the Scripting API, but as it has much more use cases, and it's already solid general abstraction of Minecraft and CNPC+ classes. + +1) This should host the Minecraft abstraction like @ClientOnly, @ServerOnly, and ALL other mc classes so that other versions like 1.7.10, 1.12.2, 1.16.5 and 1.20.1 can replace them completely with their own versions. +For annotations, we will write a custom annotation parser later to replace those annotations with their platform-correct implementations + +2) We already have systems in place, like IPlayer to represent a player, IItemStack, INbt, ICustomNpc, etc. (check src/api/java/noppes/npcs/api/) that will all be used and recycled into this. Move these kinds of classes into the platform-api. +- Don't worry about the parameterized interfaces, strip them of parameterization entirely and make them return Object in their parameterized methods. I have personally made sure that most parameters are unused (99.9% functions use raw interfaces) and we have confirmed that + it would be incredibly easy to convert the returned Object to its platform specific type with simple casting when needed. + +> **AGENT REVIEW (2026-03-15):** +> The scripting API (src/api/java/) has 202 files total. Key data for planning the move: +> +> | Category | Count | Action Needed | +> |---|---|---| +> | Already in platform-api (split-package shadow) | 30 | Already done — merge/reconcile | +> | MC-free interfaces (no MC imports) | ~131 | Move directly, strip generics from 5 entity interfaces | +> | MC-contaminated (import net.minecraft/cpw.mods.fml) | 71 | Strip MC imports, replace with platform-api equivalents or Object returns | +> | MC class stubs (net/minecraft/ vendored) | 5 | Drop — platform-api shouldn't need these | +> +> **Technical considerations for the move:** +> 1. **Generics stripping** — Only 5 interfaces use generics (entity hierarchy: IEntity, IEntityLivingBase, IEntityLiving, ICustomNpc, IPlayer). All bound to MC Entity classes. Already stripped in platform-api copies. Straightforward. +> 2. **71 MC-contaminated files** — These need method signatures rewritten to use platform-api types (Object returns where MC types were, or existing platform interfaces like `IPlayer`, `IItemStack`, `IWorld`). Biggest offenders: AbstractNpcAPI (10 MC imports), event interfaces (17 use @Cancelable from FML), entity/handler interfaces referencing MC types. +> 3. **Event system** — 20 event interfaces all use `@Cancelable` from `cpw.mods.fml`. Options: (a) create a platform `@Cancelable` annotation, (b) use the custom annotation parser mentioned in the plan, or (c) move events to a separate platform-events module. +> 4. **AbstractNpcAPI** — Abstract class (not interface) with 10 MC imports and static singleton. Needs to become an interface or be split into MC-free interface + mc1710 implementation. +> 5. **Addon impact** — The API is a git submodule used by DBC/Gecko/AW addons. Moving it means those addons need to depend on platform-api instead. Plan the transition: ship platform-api as a published artifact, update addon build files. +> 6. **30 existing split-package shadows** — These need reconciliation. The platform-api version is the MC-free base; the API version adds MC-specific methods. After the move, there should be ONE authoritative version per interface in platform-api. +> +> **Recommended execution order:** Move MC-free interfaces first (~131 files, low risk) → then tackle the 71 MC-contaminated files in batches (entity hierarchy → handlers → events → AbstractNpcAPI). + + +### package: src/ +- The main project source. Currently, everything in the source is jumbled up in here. This will be completely refactored and the appropriately diagnosed systems will be moved to either platform-api/ or core/ or remains in the new src/ +- This contains the implementation of the platform-api/ abstractions for each version of the game +- The GOAL is to HOST the LEAST amount of POSSIBLE files necessary, typically rendering, entity construction, events, etc. +- In each version, let's take 1.7.10 for example: the API abstractions in the platform-api/ noppes.npcs.api packages are represented by WRAPPERS like, ScriptNpc, ScriptItemStack, ScriptPlayer, etc. (check src/main/java/noppes/npcs/scripted/wrapper/) +that are registered to the PlatformService in Platform-API. These are the PER-VERSION implementations of our wrappers. So when in Core, when we move all logic, controllers, etc. We can simply use PlatformAPI +to supply us with an ICustomNpc or an IPlayer, etc. which represent the system. +- We should also consider abstracting a NetworkService into platform-api/ and Core system thus Packet Handling and Sync Controllers can also be fully adapted. + + + +## 2) CORE CNPC+ THAT IS ISOLATED FROM PLATFORM IMPLEMENTATION IN src/. +- package: core/ +- This is where all the CORE CNPC+ classes and logic will be implemented BASED ON the abstraction layer in platform-api +1) MUST ONLY USE platform-api/ abstractions AND NOT any of the platform implementations in src/. NO MINECRAFT WHATSOEVER. +2) All Data, Controller and Registry systems and other isolated CNPC+ system are completely ported to Core. + + + +## 3) What's currently required + ROADMAP: +1) We want the current src/api package to be moved to platform-api/. You must retain the same package structure of noppes.npcs.api and everything it encapsulates. +DO NOT CHANGE THEIR NAMES AND DO NOT CREATE SEMANTICALLY DUPLICATE INTERFACES/CLASSES . +2) TO BE DECIDED BY YOU. + +> **AGENT RECOMMENDATION FOR POINT 1:** +> Feasible. Move the API into platform-api in phases: +> - **Phase 1:** Move ~131 MC-free interfaces directly (retain package structure, strip 5 generic type params) +> - **Phase 2:** Migrate 71 MC-contaminated files by replacing MC type references with platform-api equivalents or Object returns +> - **Phase 3:** Reconcile the 30 existing split-package shadow conflicts (keep one authoritative version) +> - **Phase 4:** Update addon mods (DBC, Gecko, AW) to depend on platform-api artifact instead of git submodule +> +> **AGENT RECOMMENDATION FOR POINT 2 — SEE MIGRATION ROADMAP BELOW** + +________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________ + + + + +________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________ +VERY FIRST USER PROMPT: + +I want you to create a permanent memory session .md for this session and hook it up to the root project AGENTS.md so you always refer to it. In that memory session I want all my critical requests, +ideas and visions for whats next noted, as well as your own essential responses, as well as any important research data found by you or any subagent spawned. + +Ok so this mod is currently for minecraft forge 1.7.10. As you noticed, I am trying to upport this mod to modern minecraft versions like 1.12.2, 1.16.5 and 1.20.1 SIMULTANEOUSLY. I dont just want to work on the upport +for one version at a time for like 2-3 months, then after im done start working on the next, that's too expensive and I don't have time. I want to tackle all of them at once, to the highest possible degree. +For that purpose, I want you to give me your best suggestions for how to create a roadmap on tackling this +________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________ + + # SESSION_MEMORY.md — Multi-Version Porting Strategy @@ -7,10 +93,11 @@ **Related documents:** +- `MIGRATION_ROADMAP.md` — Phased migration plan with milestones - `MULTI_VERSION_RESEARCH.md` — Detailed external research (tools, repos, real implementations) - `MC_COUPLING_ANALYSIS.md` — Quantified MC-dependency breakdown by subsystem -- `CORE_MIGRATION_STATUS.md` — Per-file blocker analysis for core abstraction -- `CORE_PLAN.md` — Platform abstraction roadmap and naming conventions +- `BUILD_SYSTEM.md` — Gradle architecture, version-specific build requirements +- `SCRIPTING_TOOLCHAIN.md` — Java → TypeScript → Editor pipeline --- @@ -56,15 +143,20 @@ | Pattern | Change Level | Files Affected | Details | |---|---|---|---| | FML package (cpw.mods.fml → net.minecraftforge.fml) | MINOR_CHANGE | 524 files | Mass rename, mechanical | -| Entity registration | MINOR_CHANGE | 1 file (CustomNpcs.java) | Package rename | -| Block/Item registration (GameRegistry) | IDENTICAL | 18 files (62 calls in CustomItems.java) | Same API | +| Entity registration | MINOR_CHANGE | 1 file (CustomNpcs.java) | Signature change (added tracking params) | | Event system (@SubscribeEvent, EVENT_BUS) | IDENTICAL | 16+ files | Same API | | GUI handler (NetworkRegistry) | IDENTICAL | 1 file | Same API | | NBT (NBTTagCompound) | IDENTICAL | Hundreds | Same API | | World save data (WorldSavedData) | IDENTICAL | Several | Same API | | @Mod, @EventHandler, @SidedProxy | MINOR_CHANGE | ~5 files | Package rename | +| **ItemStack null→EMPTY** (1.11+) | **BREAKING_CHANGE** | **37+ null checks, 390+ files ref ItemStack** | **stack==null must become stack.isEmpty(). MASSIVE — the plan originally missed this entirely** | | Packet system (SimpleNetworkWrapper) | BREAKING_CHANGE | 100+ files | Becomes SimpleChannel | -| IInventory → IItemHandler (Capabilities) | BREAKING_CHANGE | 40+ containers | New system alongside old | +| IInventory → IItemHandler (Capabilities) | BREAKING_CHANGE | 59+ files | New capability system alongside old | +| Block/Item registration (GameRegistry) | BREAKING_CHANGE | 18 files (62 calls in CustomItems.java) | Deprecated in 1.12; must use RegistryEvent.Register | +| **World.getBlock → getBlockState** | BREAKING_CHANGE | 59+ files | Block metadata → IBlockState system | +| **getUnlocalizedName → getTranslationKey** | BREAKING_CHANGE | 59+ files | Deprecated in 1.11+ | + +> **⚠️ CORRECTION (2026-03-15):** The previous version of this table listed GameRegistry as "IDENTICAL" and was missing ItemStack nullability, getBlockState, and getTranslationKey changes entirely. The 1.12.2 port is NOT 95% mechanical — it's ~60-70% mechanical (the 524 renames are real), with 30-40% requiring real code changes that will cause crashes if missed. --- @@ -92,7 +184,7 @@ Oracle recommended separate Gradle wrappers. **This is wrong.** Evidence from re |---|---|---| | **Gradle Composite Builds** (`includeBuild`) | Each version is an independent build with its own plugin classpath | VERIFIED — only stable way to mix RFG + FG | | **Gradle Toolchains** | Run Gradle on JDK 21, compile with JDK 8 or 17 per subproject | VERIFIED — standard Gradle feature | -| **ModStitch** (github.com/isXander/modstitch) | Unifies RFG + ForgeGradle + NeoGradle in one build | THEORETICAL — needs validation | +| **ModStitch** (github.com/isXander/modstitch) | Unifies RFG + ForgeGradle + NeoGradle in one build | **UNVERIFIED** — RFG support is still an unmerged PR (#42). Do not rely on this. | | **ReplayMod Preprocessor** | `#if MC>=` directives in Java comments | VERIFIED — works, but build tooling doesn't support 1.7.10 via Loom | | **Essential Gradle Toolkit** | Wraps preprocessor with cleaner DSL | VERIFIED — plugin `gg.essential.multi-version` v0.6.7 | | **Deftu multiversion** | Production multi-version plugin (used by OneConfig) | VERIFIED — `dev.deftu.gradle.multiversion-root` v2.73.0 | @@ -118,7 +210,7 @@ The ReplayMod preprocessor **syntax** supports 1.7.10 (version `10710`). But: | Build system | Separate Gradle wrappers per leaf | Composite builds + single wrapper | **Composite builds** | | Layer count | 6 layers (platform-api → core → legacy-common → modern-common → leaves) | Preprocessor can replace family-common layers | **5 layers with optional preprocessor in version leaves** | | legacy-common / modern-common | Dedicated modules | ~100+ files could go here, BUT preprocessor handles syntactic diffs | **Start without them; add only if code duplication proves >50 files** | -| 1.7.10→1.12.2 gap | Treated as equivalent to other gaps | Mostly IDENTICAL or MINOR_CHANGE (524 package renames + 1 breaking: packets) | **1.12.2 is a mechanical port — much easier than expected** | +| 1.7.10→1.12.2 gap | Treated as equivalent to other gaps | Easier than 1.16+ but NOT trivial — 524 renames + 5 breaking changes (ItemStack null→EMPTY, IInventory, getBlockState, getTranslationKey, GameRegistry events) | **1.12.2 is ~60-70% mechanical, 30-40% real code changes** | ### Recommended Project Structure @@ -163,23 +255,27 @@ Each mc*/ has its own: ## Revised Abstraction Order (Maximum Parallelism) -The key insight: **1.12.2 is so close to 1.7.10 that most of the work is mechanical renaming (524 files of cpw.mods.fml → net.minecraftforge.fml).** This means: +The key insight: **1.12.2 is significantly closer to 1.7.10 than 1.16.5+, but it is NOT trivial.** Beyond the 524 mechanical renames, there are 5 breaking API changes affecting 200+ files total. Still, it is the easiest version jump and should be tackled first. ### Track A: Core Abstraction (enables ALL versions) 1. Finish mc1710 shadow files for migrated controllers -2. Implement `IUser` usage in core (unblocks Tier 2: ~15 files) -3. Implement `IStack` / inventory abstraction (unblocks Tier 1: ~8 files) -4. Dialog cluster → Quest cluster → PlayerData migration to core -5. Packet DTO abstraction in core -6. Command abstraction in core +2. Expand `IPlayer` / `IItemStack` / `IWorld` usage in core (use the real platform-api interfaces — DO NOT create duplicates) +3. Dialog cluster → Quest cluster → PlayerData migration to core +4. Packet DTO abstraction in core +5. Command abstraction in core -### Track B: 1.12.2 Port (CAN START IMMEDIATELY — mostly mechanical) +### Track B: 1.12.2 Port (CAN START IMMEDIATELY — easier than 1.16+ but NOT trivial) 1. Copy mc1710/ → mc1122/ -2. Mass-rename cpw.mods.fml → net.minecraftforge.fml (524 files) -3. Update entity registration (minor API change) -4. Refactor packet system (SimpleNetworkWrapper → SimpleChannel — the ONE breaking change) -5. Set up RetroFuturaGradle for 1.12.2 (confirmed: RFG supports 1.12.2) -6. Test and iterate +2. Mass-rename cpw.mods.fml → net.minecraftforge.fml (524 files, mechanical) +3. **Replace all ItemStack null checks with isEmpty()** (37+ files with null checks, 390+ files reference ItemStack — the BIGGEST hidden change) +4. Update block/item registration to RegistryEvent pattern (18 files, 62 calls in CustomItems.java) +5. Update entity registration signature (1 file) +6. Replace getUnlocalizedName → getTranslationKey (59+ files) +7. Address World.getBlock → getBlockState usage (59+ files) +8. Refactor packet system (SimpleNetworkWrapper → SimpleChannel — structural rewrite) +9. Begin IInventory → IItemHandler migration for containers (59+ files, can be incremental) +10. Set up RetroFuturaGradle for 1.12.2 (confirmed: RFG supports 1.12.2) +11. Test and iterate ### Track C: 1.16.5 Port (start after Track A Phase 1-3) 1. Create mc1165/ with ForgeGradle 6 @@ -205,7 +301,7 @@ The key insight: **1.12.2 is so close to 1.7.10 that most of the work is mechani ### 1.7.10 — Full Primary (unchanged) All features, full parity. This is the production build. -### 1.12.2 — "Bridge Build" (EASIEST — mostly mechanical port) +### 1.12.2 — "Bridge Build" (Closest to 1.7.10, but has real breaking changes) - NPC spawn, persist, despawn lifecycle - Dialog system, Quest system, Faction system - Core networking (NPC sync, player data) @@ -232,9 +328,9 @@ All features, full parity. This is the production build. 2. **Don't mirror Minecraft class-for-class in platform-api** — keep interfaces coarse and purpose-driven 3. **Don't promise full GUI parity on modern versions first** — 212 files, completely different per version, do LAST 4. **Don't let preprocessor guards spread into core/** — only in version-leaf code -5. **Don't try to abstract scripting, abilities, entities, or recipes** — Tier 4-5, rewrite per-version -6. **1.12.2 is much easier than you think** — 95% of APIs are identical/renamed, only packets truly break -7. **Composite builds, not separate wrappers** — one Gradle wrapper, `includeBuild` per version leaf +5. **1.12.2 is easier than 1.16+ but NOT trivial** — 524 mechanical renames + 5 breaking changes (ItemStack null→EMPTY, IInventory, getBlockState, getTranslationKey, GameRegistry events) affecting 200+ files +6. **Composite builds, not separate wrappers** — one Gradle wrapper, `includeBuild` per version leaf +7. **API merge is a phased operation** — move MC-free interfaces first (~131), then strip MC imports from the remaining 71. Don't try to move everything in one shot. --- diff --git a/AGENTS.md b/AGENTS.md index 0e6150f39..cd321d1ed 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,14 +4,14 @@ **All documents below this line are created BY and FOR agents operating on this codebase.** This is the master architecture reference. Before any work: 1. Read `.AGENTS/SESSION_MEMORY.md` — strategic vision, roadmap, critical decisions -2. Read `.AGENTS/CORE_PLAN.md` — platform abstraction design and naming conventions -3. Skim `.AGENTS/FORBIDDEN_PRACTICES.md` — architectural guardrails (NEVER violate these) -4. Reference `.AGENTS/MC_COUPLING_ANALYSIS.md` — what's MC-dependent, migration priority +2. Skim `.AGENTS/FORBIDDEN_PRACTICES.md` — architectural guardrails (NEVER violate these) +3. Reference `.AGENTS/MC_COUPLING_ANALYSIS.md` — what's MC-dependent, migration priority **If working on multi-version porting**, also read: - `.AGENTS/MULTI_VERSION_RESEARCH.md` — real-world strategies, tools, pitfalls - `.AGENTS/BUILD_SYSTEM.md` — Gradle architecture, version-specific build requirements +- `.AGENTS/MIGRATION_ROADMAP.md` — phased migration plan with milestones --**IMPORTANT** ALWAYS CHECK OUT `SESSION_MEMORY.md` WHEN WORKING ON MIGRATING/UPPORTING THIS PROJECT TO LATER MINECRAFT VERSIONS. +-**IMPORTANT** ALWAYS CHECK OUT `.AGENTS/SESSION_MEMORY.md` WHEN WORKING ON MIGRATING/UPPORTING THIS PROJECT TO LATER MINECRAFT VERSIONS. --- @@ -35,7 +35,7 @@ Minecraft 1.7.10 Forge mod. NPC customization, AI, quests, abilities, scripting - **Split-package shadow**: Core class in `core/` + mc1710 version in `src/main/java/` same package. mc1710 shadows core at compile time (adds `implements IFaction`, SyncController calls, MC-specific methods). - **Platform abstraction**: `PlatformServiceHolder.get()` → `PlatformService` impl registered at mod init. - **NBT wrapping**: `NBTTagCompound` → `INBTCompound`, `new NBTTagCompound()` → `NBT.compound()`. -- **Entity wrapping**: `EntityPlayer` → `IUser` (platform-api), mc1710 provides `PlayerWrapper`. +- **Entity wrapping**: `EntityPlayer` → `IPlayer` (platform-api), mc1710 provides `PlayerWrapper`. ## Subsystem Location Map @@ -67,10 +67,9 @@ Minecraft 1.7.10 Forge mod. NPC customization, AI, quests, abilities, scripting | **TypeScript Gen** | `gradle-plugins/src/` | Gradle plugin: Java API → `.d.ts` definitions | ## Core Migration Status -- **183 files** abstracted to `core/` + `platform-api/` out of ~1,810 total +- **188 files** abstracted to `core/` + `platform-api/` out of ~1,810 total - Migrated: Faction, Magic, Transport, Tag, GlobalData controllers + 60+ data classes -- See `CORE_MIGRATION_STATUS.md` for per-file blocker analysis -- See `CORE_PLAN.md` for migration roadmap and naming conventions +- See `SESSION_MEMORY.md` for migration roadmap and current strategy ## NEVER / DO NOT Rules @@ -80,9 +79,9 @@ Minecraft 1.7.10 Forge mod. NPC customization, AI, quests, abilities, scripting 4. **NEVER touch recipe system for migration** — `RecipeCarpentry` extends `ShapedRecipes`, `RecipeController` uses `CraftingManager`. 5. **NEVER import MC classes in `core/` or `platform-api/`** — use platform interfaces only. 6. **NEVER import wrapper classes in `core/`** — only interfaces from `platform-api/`. -7. **Platform interface naming**: Short `I` prefix, no `Platform` in name (`IUser` not `IPlatformUser`). +7. **Platform interface naming**: Use the existing scripting API names as-is (`IPlayer`, `IEntity`, `IItemStack`, `IWorld`). Do NOT create semantically duplicate interfaces. 8. **MC1710 wrapper naming**: `[Thing]Wrapper` — no `MC1710` prefix. -9. **Scripting API** (`IPlayer`, `IEntity`, `ICustomNpc`) is a **separate concern** from platform interfaces — different package, different purpose. Do not conflate. +9. **Scripting API** (`IPlayer`, `IEntity`, `ICustomNpc`) is being **merged into platform-api** — same package (`noppes.npcs.api.*`), stripped of MC type parameters. The MC-free versions live in `platform-api/`, version-specific extensions live in each version leaf's shadow. See `SESSION_MEMORY.md` Phase 0B/0C for the migration plan. 10. **Split-package rule**: When a class exists in both `core/` and `src/main/java/` with same package, mc1710 version shadows core. Never break this contract. ## Build & Run @@ -130,8 +129,8 @@ Minecraft 1.7.10 Forge mod. NPC customization, AI, quests, abilities, scripting - `MULTI_VERSION_RESEARCH.md` — External research: real multi-version mod repos, build tools, preprocessor details - `MC_COUPLING_ANALYSIS.md` — Quantified MC-dependency breakdown by subsystem (1,424 files analyzed) - `FORBIDDEN_PRACTICES.md` — Anti-patterns, deprecated components, architectural guardrails -- `CORE_MIGRATION_STATUS.md` — Detailed per-file blocker analysis for core migration -- `CORE_PLAN.md` — Migration roadmap, naming conventions, architecture decisions +- `MIGRATION_ROADMAP.md` — Phased migration plan with milestones +- `BUILD_SYSTEM.md` — Gradle architecture, version-specific build requirements - `CHANGELOG.md` — Version history - `todo.txt` — Pending tasks - `dts-patches/` — Manual patches applied to generated TypeScript definitions diff --git a/CORE_MIGRATION_STATUS.md b/CORE_MIGRATION_STATUS.md deleted file mode 100644 index 342e4942c..000000000 --- a/CORE_MIGRATION_STATUS.md +++ /dev/null @@ -1,203 +0,0 @@ -# Core Migration Status - -**Last updated:** 2026-03-13 -**Total:** 140 core + 43 platform-api = **183 abstracted files** -**Remaining in src/main/java:** ~1,627 files - ---- - -## What's Done - -### Controllers in Core (8 files) -| Controller | Data Classes in Core | Notes | -|---|---|---| -| `GlobalDataController` | _(self-contained)_ | Async save via CustomNPCsThreader | -| `ServerTagMapController` | `TagMap`, `Tag` | Clone tab/folder management | -| `TransportController` | `TransportCategory`, `TransportLocation` | Full CRUD | -| `FactionController` | `Faction` | SyncController calls stubbed | -| `MagicController` | `Magic`, `MagicCycle`, `MagicAssociation`, `MagicEntry`, `MagicData` | `createDefaults()` overrideable for ItemStack setup | -| `TagController` | `Tag` | UUID tag helpers migrated too | -| `CategoryManager` | `Category` | Filesystem-based category management | -| `APIRegistry` | _(self-contained)_ | Name→URL registry | - -### Data Classes in Core (~60+ files) -See `core/src/main/java/` for full listing. Key clusters: -- Transport system (TransportCategory, TransportLocation) -- Faction system (Faction) -- Magic system (Magic, MagicCycle, MagicAssociation, MagicEntry, MagicData) -- Tag system (Tag, TagMap) -- Energy display/combat/anchor/homing/lifespan/lightning/panel/barrier/charging data -- Ability enums + ConditionFilter -- Attribute system (AttributeDefinition, PlayerAttribute, PlayerAttributeMap) -- Profile system (Slot, ProfileOptions, ProfileInfoEntry, ProfileOperation) -- Dialog display data (DialogImage, DialogColorData, Lines, Line) -- Frame/animation data (Frame, FramePart, HitboxData, TintData) -- Player data fragments (PlayerDialogData, PlayerTransportData, PlayerEffect, PlayerEffectData, AbilityHotbarData) -- Auction (AuctionFilter) -- Misc (SkinOverlay, InnDoorData, ItemDisplayData, PartyOptions, TraderStock, CloneFolder) - -### Infrastructure in Core -- `NBTTags.java` — All map/set/list NBT helpers using INBTCompound/INBTList -- `NBT.java` — Factory: `NBT.compound()`, `NBT.list()` -- `CustomNPCsThreader` — Thread pool for async saves -- Network enums (EnumSyncType, EnumDataPacket, EnumRequestPacket, etc.) -- Developer registry - ---- - -## TODO Stubs in Core (mc1710 must override/add) - -### Scripting API Interface Implementations -These core classes do NOT implement their scripting API interfaces. The mc1710 split-package shadow must add `implements IXxx`: - -| Core Class | mc1710 Must Add | Interface Location | -|---|---|---| -| `Faction` | `implements IFaction` | `src/api/java/.../IFaction.java` | -| `FactionController` | `implements IFactionHandler` | `src/api/java/.../IFactionHandler.java` | -| `Magic` | `implements IMagic` | `src/api/java/.../IMagic.java` | -| `MagicController` | `implements IMagicHandler` | `src/api/java/.../IMagicHandler.java` | -| `TagController` | `implements ITagHandler` | `src/api/java/.../ITagHandler.java` | -| `TransportController` | `implements ITransportHandler` | (referenced in TODO) | - -### SyncController Calls -All core controllers stub out SyncController network sync. mc1710 must re-add these: - -| Core File | Stubbed Method | SyncController Call | -|---|---|---| -| `FactionController` | `saveFaction()` | `SyncController.syncUpdate(EnumSyncType.FACTION, -1, compound)` | -| `FactionController` | `delete()` | `SyncController.syncRemove(EnumSyncType.FACTION, id)` | -| `MagicController` | `saveMagic()` | `SyncController.syncUpdate(EnumSyncType.MAGIC, -1, compound)` | -| `MagicController` | `removeMagic()` | `SyncController.syncRemove(EnumSyncType.MAGIC, magicID)` | -| `MagicController` | `saveCycle()` | `SyncController.syncUpdate(EnumSyncType.MAGIC_CYCLE, -1, compound)` | -| `MagicController` | `removeCycle()` | `SyncController.syncRemove(EnumSyncType.MAGIC_CYCLE, categoryId)` | -| `TagController` | _(not present — delete() doesn't sync in core)_ | `SyncController.syncRemove` if needed | - -### EntityPlayer / Entity Methods -Methods that require MC entity types, left out of core: - -| Core Class | Stubbed Methods | Depends On | -|---|---|---| -| `Faction` | `isFriendlyToPlayer(EntityPlayer)`, `isAggressiveToPlayer(EntityPlayer)`, `isNeutralToPlayer(EntityPlayer)` | `PlayerData.get(player).factionData` | -| `Faction` | `isAggressiveToNpc(EntityNPCInterface)` | `entity.faction.id` | -| `Faction` | `playerStatus(IPlayer)`, `isAggressiveToNpc(ICustomNpc)` | Scripting API entity types | -| `Faction` | `isFriendlyToPlayer(IPlayer)`, etc. | Delegates to EntityPlayer overloads | -| `TagController` | `sendCategoryTagMap(EntityPlayerMP, ...)` | `GuiDataPacket` | -| `TransportController` | `saveLocation(int, NBTTagCompound, EntityNPCInterface)` | `RoleTransporter`, `EnumRoleType` | -| `PlayerEffect` | `getEffect()` | `CustomEffectController` (mc1710 only) | -| `PlayerEffect` | `getAPI()` | `IPlayer` scripting API | - -### ItemStack / GameRegistry -Methods that require MC item types: - -| Core Class | Stubbed Feature | Depends On | -|---|---|---| -| `Magic` | `ItemStack item` field | `net.minecraft.item.ItemStack` | -| `Magic` | `setItem(ItemStack)` / `getItem()` | `GameRegistry.findUniqueIdentifierFor` | -| `Magic` | Item resolution in `readNBT`/`writeNBT` | `GameRegistry.findItem(modID, itemName)` | -| `MagicController` | Default magic ItemStack assignment in `createDefaults()` | `CustomItems.*` item references | - -### NBTTags Omitted Methods -Methods left out of core `NBTTags.java` (stay in mc1710 version): - -| Method | Reason | -|---|---| -| `getItemStackList`, `getItemStackArray` | Uses `NoppesUtilServer.readItem()` + `ItemStack` | -| `nbtItemStackList`, `nbtItemStackArray` | Uses `NoppesUtilServer.writeItem()` + `ItemStack` | -| `nbtDoubleList` | Uses `NBTTagDouble` directly | -| `GetScript`, `GetScriptOld`, `NBTScript` | Uses `IScriptHandler` / `IScriptUnit` | -| `getIntAt` | Uses `NBTTagInt.func_150287_d()` | - ---- - -## Blocked Migrations & What Unblocks Them - -### Tier 1: Blocked by ItemStack/Inventory Abstraction -**Unblock:** Add `IStack` wrapping to `PlatformService`, or create inventory abstraction - -| File | Blocker | -|---|---| -| `Bank.java` | `NpcMiscInventory` (ItemStack-based currency/upgrade inventories) | -| `BankController.java` | Depends on `Bank` | -| `AuctionClaim.java` | `ItemStack.writeToNBT` / `readFromNBT` | -| `AuctionListing.java` | `ItemStack` operations | -| `AuctionBlacklist.java` | `GameRegistry`, `ItemStack` | -| `LinkedItem.java` | `ItemStack`, `Constants.NBT` | -| `RecipeAnvil.java` | `ItemStack`, `Constants.NBT` | -| `PlayerItemGiverData.java` | `JobItemGiver` (roles package) | - -### Tier 2: Blocked by EntityPlayer Abstraction -**Unblock:** Implement Phase 0-1 `IUser` wrappers + use in core - -| File | Blocker | -|---|---| -| `Availability.java` | `EntityPlayer` checks, `StatCollector`, `MathHelper` | -| `FactionOptions.java` | `EntityPlayer`, `PlayerFactionData`, `ChatComponentTranslation` | -| `DialogOption.java` | `EntityPlayer` via `dialog.availability.isAvailable(player)` | -| `Dialog.java` | `EntityPlayer`, `ICompatibilty`, `VersionCompatibility`, scripting API | -| `DialogCategory.java` | References `Dialog` (same-package) | -| `Quest.java` | `EntityPlayer`, `Availability`, scripting API | -| `QuestCategory.java` | References `Quest` (same-package) | -| `QuestData.java` | References `Quest` (same-package) | -| `CustomEffect.java` | `EntityPlayer`, `Constants.NBT` | -| `Party.java` | `EntityPlayer`, `EntityPlayerMP`, FML imports | -| `PlayerData.java` | `EntityPlayer` throughout | -| `PlayerFactionData.java` | `EntityPlayer`, `PlayerData` | -| `All Player*Data classes` | `EntityPlayer` / `EntityPlayerMP` coupling | -| `IRequirementChecker.java` | `EntityPlayer` in `check()` method | - -### Tier 3: Blocked by Entity/World Abstraction -**Unblock:** `IMob`, `IGameWorld` wrappers - -| File | Blocker | -|---|---| -| `SpawnData.java` | Extends `WeightedRandom.Item`, `DimensionManager`, `EntityList` | -| `SpawnController.java` | `WeightedRandom.getRandomItem()` | -| `Animation.java` | `@SideOnly`, `EntityNPCInterface`, `EventHooks` | -| `AnimationData.java` | `EntityPlayer`, `AxisAlignedBB`, dimension access | -| `DataTransform.java` | `EntityNPCInterface`, `EntityCustomNpc` throughout | -| `MarkData.java` | `IExtendedEntityProperties`, `EntityLivingBase` | -| `TelegraphInstance.java` | `Entity`, `World` | - -### Tier 4: Blocked by Script System (DO NOT TOUCH YET) -| File | Blocker | -|---|---| -| `All I*Script*.java` | Script handler/unit interfaces | -| `ScriptHandler.java`, `SingleScriptHandler.java`, etc. | Script execution | -| `AbilityScript.java`, `ChainedAbilityScript.java` | Script containers | -| `EffectScript.java`, `LinkedItemScript.java` | Script containers | -| `DataScript.java` | FML, World, entities + scripting | -| `Action.java` + action framework | `ScriptContainer` dependency | - -### Tier 5: Blocked by Heavy MC Coupling (Long-term) -| File | Blocker | -|---|---| -| `RecipeCarpentry.java` | Extends `ShapedRecipes` | -| `RecipeController.java` | `CraftingManager`, `InventoryCrafting` | -| `Ability.java` (kamkeel) | 30+ MC imports (Block, Entity, DamageSource, Vec3, World) | -| `All ability type/ classes` | Depend on `Ability.java` | -| `ChunkController.java` | `ForgeChunkManager` | -| `ProfileController.java` | EntityPlayer lifecycle, Mojang API, events | -| `SyncController.java` | ByteBuf, packets, Minecraft server | - ---- - -## Recommended Next Steps (in order) - -### 1. mc1710 Shadow Files for Migrated Controllers -The mc1710 versions (`src/main/java/`) of FactionController, MagicController, TagController need to be updated to: -- Add `implements IFactionHandler` / `IMagicHandler` / `ITagHandler` -- Re-add SyncController calls in save/delete methods -- Re-add EntityPlayer/IPlayer methods that were stubbed -- Override `createDefaults()` in MagicController to set ItemStack items - -### 2. IUser Implementation (Phase 0-1 of plan) -Creates the biggest unblock — enables migration of Availability, FactionOptions, Dialog system, Quest system, CustomEffect, all Player*Data classes. - -### 3. IStack / Inventory Abstraction -Unblocks Bank, AuctionClaim/Listing, LinkedItem — the ItemStack-dependent data classes. - -### 4. Dialog + Quest Cluster Migration -Once IUser exists: migrate Dialog → DialogOption → DialogCategory → DialogController as a cluster. Then Quest → QuestCategory → QuestData → QuestController. - -### 5. NBTJsonUtil to Core -Many controllers (Dialog, Quest, CustomEffect) use NBTJsonUtil for JSON file storage. Creating a core version would unblock those controllers. diff --git a/CORE_PLAN.md b/CORE_PLAN.md deleted file mode 100644 index 2982bcfd6..000000000 --- a/CORE_PLAN.md +++ /dev/null @@ -1,164 +0,0 @@ -# Core Abstraction Plan - -**Last updated:** 2026-03-13 -**Current state:** 140 core + 43 platform-api = **183 abstracted files** out of ~1,810 - ---- - -## Naming Conventions - -### Platform Interfaces (`platform-api/.../kamkeel/npcs/platform/entity/`) -| Interface | Wraps | Extends | -|---|---|---| -| `IMob` | Any entity (Entity) | — | -| `ILiving` | Living entity (EntityLivingBase) | `IMob` | -| `IUser` | Player (EntityPlayerMP) | `ILiving` | -| `INpc` | NPC entity (EntityNPCInterface) | `ILiving` *(not yet created)* | -| `IStack` | ItemStack | — | -| `IGameWorld` | World | — | -| `IDamage` | DamageSource | — | - -### MC1710 Wrapper Implementations (`src/.../kamkeel/npcs/wrapper/platform/`) -| Wrapper | Implements | -|---|---| -| `EntityWrapper` | `IMob` | -| `LivingWrapper` | `ILiving` | -| `PlayerWrapper` | `IUser` | -| `StackWrapper` | `IStack` | -| `WorldWrapper` | `IGameWorld` | -| `DamageWrapper` | `IDamage` | - -### NBT Wrappers (`src/.../noppes/npcs/wrapper/nbt/`) -| Wrapper | Implements | -|---|---| -| `NBTWrapper` | `INBTCompound` | -| `NBTListWrapper` | `INBTList` | -| `NBTWrapperFactory` | `NBTFactory` | -| `NBTWrapperIO` | `NBTIO` | - -### Naming Rules -- **Platform interfaces**: Short `I` prefix names. No `Platform` in the name. -- **MC1710 wrappers**: `[Thing]Wrapper` — no `MC1710` prefix. Each platform module's wrappers live in their own Gradle module so no collision. -- **Core code** never imports wrappers or MC classes. Only interfaces from `platform-api`. -- **Scripting API** (`IPlayer`, `IEntity`, `ICustomNpc`) stays unchanged — different package, different purpose. - ---- - -## Architecture - -``` -platform-api/ → Interfaces only (INBTCompound, IUser, IStack, etc.) - ↑ - core/ → All game logic (controllers, data classes, enums, utils) - ↑ -src/main/java/ (mc1710) → MC 1.7.10 implementations (wrappers, entities, GUI, packets) -``` - -### Key Patterns -- **NBT**: `NBTTagCompound` → `INBTCompound`, `new NBTTagCompound()` → `NBT.compound()` -- **File I/O**: `CompressedStreamTools` → `PlatformServiceHolder.get().readCompressedNBT()` -- **Logging**: `LogWriter` → `PlatformServiceHolder.get().logError()` -- **Paths**: `CustomNpcs.getWorldSaveDirectory()` → `PlatformServiceHolder.get().getWorldSaveDirectory()` -- **Entity params**: `EntityPlayer` → `IUser`, `EntityNPCInterface` → `INpc` -- **Split-package shadow**: Core class in `core/`, mc1710 version in `src/main/java/` same package — shadows at compile time (adds `implements IFaction`, SyncController calls, etc.) - -### What stays mc1710-only -- Entity classes (extend MC Entity directly) -- GUI / rendering (`@SideOnly(Side.CLIENT)`) -- Packets / network (ByteBuf, AbstractPacket) -- SyncController calls -- Scripting API interfaces (`IFaction`, `IMagicHandler`, etc.) -- `FieldDef` / ability GUI definitions -- Anything touching `GameRegistry`, `ForgeChunkManager`, `WeightedRandom` - ---- - -## Next Steps (in priority order) - -### Step 1: mc1710 Shadow Files for Migrated Controllers -The core versions of FactionController, MagicController, TagController are done but the mc1710 shadow files haven't been updated yet. - -**For each controller, the mc1710 version needs:** -- `implements IFactionHandler` / `IMagicHandler` / `ITagHandler` -- SyncController calls re-added in save/delete methods -- EntityPlayer/IPlayer methods re-added -- MagicController: override `createDefaults()` to set ItemStack items - -**Files to update:** -- `src/main/java/noppes/npcs/controllers/FactionController.java` -- `src/main/java/noppes/npcs/controllers/MagicController.java` -- `src/main/java/noppes/npcs/controllers/TagController.java` - -### Step 2: IUser Implementation -The `IUser` interface exists but isn't used by any core class yet. This is the **single biggest unblock** — it gates ~20 data classes. - -**What to do:** -- Start using `IUser` in core data classes that need player references -- Replace `EntityPlayer` params with `IUser` in migrated methods -- Wrap at mc1710 boundaries: `PlatformServiceHolder.get().wrapPlayer(entityPlayer)` - -### Step 3: Availability → Core -`Availability.java` is the gatekeeper for Dialog and Quest systems. Once `IUser` is usable: -- Migrate `isAvailable(EntityPlayer)` → `isAvailable(IUser)` -- `StatCollector` calls need a platform abstraction or extraction -- `MathHelper` calls can be replaced with plain Java math - -### Step 4: Dialog Cluster Migration -Depends on Availability being in core. - -**Migration order:** -1. `DialogOption` → core (uses `dialog.availability.isAvailable()`) -2. `Dialog` → core (uses DialogOption, Availability, Lines/Line already in core) -3. `DialogCategory` → core (just references Dialog) -4. `DialogController` → core (file I/O pattern same as FactionController) - -**Blockers to resolve:** -- `NBTJsonUtil` — Dialog/Quest controllers use this for JSON file storage. Need a core version or platform abstraction. -- `ICompatibilty` / `VersionCompatibility` — Dialog.readNBT references these - -### Step 5: Quest Cluster Migration -Same pattern as Dialog, depends on Availability. - -**Migration order:** -1. `Quest` → core -2. `QuestCategory` → core -3. `QuestData` → core -4. `QuestController` → core - -### Step 6: IStack / Inventory Abstraction -Unblocks Bank, AuctionClaim/Listing, LinkedItem. - -**What to do:** -- Use `IStack` in core data classes that handle items -- May need `IInventory` or similar for `NpcMiscInventory` abstraction - -### Step 7: Player Data Classes -Once `IUser` is proven and Availability/Dialog/Quest are done: -- `PlayerData` → core (heavy, central class) -- `PlayerFactionData` → core -- `PlayerDialogData` (already in core) -- `PlayerTransportData` (already in core) -- Remaining `Player*Data` classes - -### Step 8: INpc + Entity Data Sub-Objects -Create `INpc` interface, then migrate NPC data sub-objects: -- `DataDisplay`, `DataStats`, `DataAI`, `DataAdvanced` -- `DataTimers`, `DataSkinOverlays` -- These are NBT serialization classes — straightforward migration - ---- - -## DO NOT TOUCH (yet) - -- **Script system** — ScriptHandler, ScriptContainer, all I*Script* interfaces, Action framework -- **Ability.java** and ability type classes — 30+ MC imports, deeply coupled -- **Entity classes** — extend MC Entity, stay platform-side -- **Recipe system** — extends MC recipe classes - ---- - -## Reference - -- **Blocker details**: See `CORE_MIGRATION_STATUS.md` for per-file blocker analysis -- **Build**: `./gradlew.bat build` from project root -- **Pre-existing build warning**: `ClientEventHandler.java:79` orphaned token (not ours) diff --git a/core/AGENTS.md b/core/AGENTS.md index 3dd66ee32..8e0bf31e0 100644 --- a/core/AGENTS.md +++ b/core/AGENTS.md @@ -30,8 +30,9 @@ Core code must **never** import: | `CompressedStreamTools` | `PlatformServiceHolder.get().readCompressedNBT()` | | `LogWriter` | `PlatformServiceHolder.get().logError()` | | `CustomNpcs.getWorldSaveDirectory()` | `PlatformServiceHolder.get().getWorldSaveDirectory()` | -| `EntityPlayer` param | `IUser` (via platform-api) | -| `EntityNPCInterface` param | `INpc` (via platform-api, not yet created) | +| `EntityPlayer` param | `IPlayer` (via platform-api — `noppes.npcs.api.entity.IPlayer`) | +| `ItemStack` param | `IItemStack` (via platform-api — `noppes.npcs.api.item.IItemStack`) | +| `World` param | `IWorld` (via platform-api — `noppes.npcs.api.IWorld`) | ## Split-Package Shadows @@ -40,16 +41,10 @@ Core classes share packages with mc1710 classes. The mc1710 version can: - Re-add `SyncController` calls for network sync - Override methods that need `ItemStack`, `EntityPlayer`, etc. -## DO NOT TOUCH (Forbidden Zones) - -- **Script system** — ScriptHandler, ScriptContainer, I*Script*, Action framework -- **Ability system** — Ability.java and ability type classes (30+ MC imports) -- **Entity classes** — extend MC Entity directly -- **Recipe system** — extends MC recipe classes - ## Adding New Core Code 1. Ensure zero MC imports — use platform-api interfaces 2. NBT via `NBT.compound()` / `NBT.list()`, file I/O via `PlatformServiceHolder` 3. Stub out methods needing MC types — mc1710 shadow adds them 4. Follow existing package structure (controllers → `controllers/`, data → `controllers/data/`) +5. **NEVER create duplicate interface names** — use `IPlayer`, `IItemStack`, `IWorld`, `IEntity` etc. from platform-api as-is diff --git a/core/src/main/java/AGENTS.md b/core/src/main/java/AGENTS.md index a71e18dce..6ab9dac42 100644 --- a/core/src/main/java/AGENTS.md +++ b/core/src/main/java/AGENTS.md @@ -2,7 +2,7 @@ ## What This Is MC-free module containing game logic, enums, data classes, and controllers that compile without -Minecraft imports. Uses `platform-api/` interfaces for MC operations. 183 files migrated so far. +Minecraft imports. Uses `platform-api/` interfaces for MC operations. 188 files migrated so far. Dependency: `platform-api` ← `core` ← `mc1710 (root src)`. ## Split-Package Shadow Pattern @@ -10,7 +10,7 @@ Core classes and mc1710 classes share the **same package**. At compile time, mc1 core by adding MC-specific functionality: ``` -core/ Faction.java → Pure data + INBTCompound serialization +core/ Faction.java → Pure data + INbt serialization src/ Faction.java → adds `implements IFaction`, SyncController calls, EntityPlayer methods ``` @@ -31,7 +31,7 @@ All game enums. No MC imports. Domains: - **Misc**: `EnumBardInstrument`, `EnumDayTime`, `EnumParticleType`, `MarkType`, `NBTTypes`, `EnumNpcToolMaterial` ### controllers/ (8 files) -Migrated controller singletons using `INBTCompound` instead of `NBTTagCompound`: +Migrated controller singletons using `INbt` instead of `NBTTagCompound`: | Controller | Status | |---|---| @@ -75,23 +75,17 @@ Migrated data classes. Key groups: - `developer/` — `Developer` registry ## Platform Abstraction -Core uses `platform-api/` interfaces: -- `INBTCompound` / `INBTList` instead of `NBTTagCompound` / `NBTTagList` +Core uses `platform-api/` interfaces (the real ones from `noppes.npcs.api.*`): +- `INbt` / `INbtList` instead of `NBTTagCompound` / `NBTTagList` - `NBT.compound()` / `NBT.list()` factory methods instead of `new NBTTagCompound()` - `PlatformServiceHolder.get()` for file I/O, logging, world save directory access -- `IUser` for player references (not yet widely implemented — blocks many migrations) +- `IPlayer` for player references, `IItemStack` for items, `IWorld` for worlds ## Migration Status -183/~1810 files migrated. Blockers for remaining classes: -- **IUser wrapper** needed for Availability, Dialog, Quest migrations -- **IStack wrapper** needed for item-dependent classes (inventory, trading, recipes) -- **Entity abstractions** not planned — entities stay mc1710-side permanently -- **Script system** not planned for migration — deeply coupled to engines - -See `CORE_MIGRATION_STATUS.md` and `CORE_PLAN.md` at project root for details. +188/~1810 files migrated. See `.AGENTS/SESSION_MEMORY.md` for the full migration roadmap. ## Forbidden - **NEVER import net.minecraft.* in core/** — use platform-api interfaces only - **NEVER import wrapper classes in core/** — only interfaces from platform-api/ - **NEVER break split-package shadow** — core class must compile alone, mc1710 adds MC logic -- **NEVER add IUser/IStack to core until platform-api interfaces are finalized** +- **NEVER create duplicate interface names** — use the existing `IPlayer`, `IItemStack`, `IWorld`, `IEntity` etc. from platform-api diff --git a/platform-api/AGENTS.md b/platform-api/AGENTS.md index 1eceb8a75..f6edbfe28 100644 --- a/platform-api/AGENTS.md +++ b/platform-api/AGENTS.md @@ -1,32 +1,39 @@ # platform-api/ — Interface Definitions MC-free interfaces consumed by `core/`. Each MC version module provides implementations. +The scripting API interfaces (`noppes.npcs.api.*`) are being merged into this module. ## Structure ``` -kamkeel/npcs/platform/ → PlatformService, PlatformServiceHolder, annotations -noppes/npcs/api/ → Entity, item, handler, NBT interfaces -noppes/npcs/platform/nbt/ → NBTFactory, NBTIO abstractions +kamkeel/npcs/platform/ → PlatformService, PlatformServiceHolder, annotations +kamkeel/npcs/platform/config/ → IConfigProvider +noppes/npcs/api/ → Entity, item, handler, ability, NBT interfaces (from scripting API) +noppes/npcs/platform/nbt/ → NBTFactory, NBTIO abstractions ``` ## Naming Conventions -- **Short `I` prefix**: `IMob`, `ILiving`, `IUser`, `INpc`, `IStack`, `IGameWorld`, `IDamage` +- **Use the existing scripting API names as-is**: `IPlayer`, `IEntity`, `IItemStack`, `IWorld`, `ICustomNpc`, `INbt`, etc. +- **NEVER create semantically duplicate interfaces** — no `IUser`, `IStack`, `IGameWorld`, `IMob`. These don't exist and never should. - **No `Platform` prefix** on interfaces — only `PlatformService` itself uses it -- **Scripting API** (`IPlayer`, `IEntity`, `ICustomNpc`) is in the same package but separate concern +- **MC1710 wrappers**: `[Thing]Wrapper` — `PlayerWrapper`, not `MC1710PlayerWrapper` -## Key Interfaces +## Key Interfaces (actual, from noppes.npcs.api.*) -| Interface | Wraps | Extends | +| Interface | Wraps | Package | |---|---|---| -| `IMob` | Entity | — | -| `ILiving` | EntityLivingBase | `IMob` | -| `IUser` | EntityPlayerMP | `ILiving` | -| `INpc` | EntityNPCInterface | `ILiving` *(planned)* | -| `IStack` | ItemStack | — | -| `IGameWorld` | World | — | -| `IDamage` | DamageSource | — | +| `IPlayer` | EntityPlayerMP | `noppes.npcs.api.entity` | +| `IEntity` | Entity | `noppes.npcs.api.entity` | +| `IEntityLivingBase` | EntityLivingBase | `noppes.npcs.api.entity` | +| `IEntityLiving` | EntityLiving | `noppes.npcs.api.entity` | +| `ICustomNpc` | EntityCustomNpc | `noppes.npcs.api.entity` | +| `IItemStack` | ItemStack | `noppes.npcs.api.item` | +| `IWorld` | World | `noppes.npcs.api` | +| `INbt` | NBTTagCompound | `noppes.npcs.api` | +| `INbtList` | NBTTagList | `noppes.npcs.api` | +| `IPos` | BlockPos | `noppes.npcs.api` | +| `IDamageSource` | DamageSource | `noppes.npcs.api` | ## PlatformService @@ -36,4 +43,4 @@ Central SPI (`kamkeel.npcs.platform.PlatformService`): NBT factory + I/O, file p - **Interfaces only** — no MC imports allowed - `@ClientOnly` / `@ServerOnly` annotations for side-specific contracts -- New interfaces follow `I[Thing]` naming — keep names short +- New interfaces use existing API names — check `src/api/java/` before creating anything new diff --git a/src/api b/src/api index 5cb3a5bee..d2194bb10 160000 --- a/src/api +++ b/src/api @@ -1 +1 @@ -Subproject commit 5cb3a5beefe4bae340da43fb3a05428afa30d6fd +Subproject commit d2194bb10acc01c28ca2c3ad46e2cd15a6803b32