mirror of
https://github.com/KAMKEEL/CustomNPC-Plus.git
synced 2026-11-17 12:15:11 +00:00
137 lines
9.0 KiB
Markdown
137 lines
9.0 KiB
Markdown
# AGENTS.md — CustomNPC-Plus
|
|
|
|
## ⚠️ AGENT CONTEXT — Read First
|
|
**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. 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 `.AGENTS/SESSION_MEMORY.md` WHEN WORKING ON MIGRATING/UPPORTING THIS PROJECT TO LATER MINECRAFT VERSIONS.
|
|
---
|
|
|
|
|
|
## What This Is
|
|
Minecraft 1.7.10 Forge mod. NPC customization, AI, quests, abilities, scripting (JS/Java), economy.
|
|
~2,170 source files. Entry: `CustomNpcs.java` (`@Mod`). Packages: `noppes.npcs.*`, `kamkeel.npcs.*`.
|
|
|
|
## Module Structure
|
|
|
|
| Module | Path | Purpose | MC Dependencies |
|
|
|---|---|---|---|
|
|
| **platform-api** | `platform-api/` | Interfaces only (`PlatformService`, `NBTFactory`, `INBTCompound`) | None |
|
|
| **core** | `core/` | MC-free game logic: controllers, data classes, enums, utils | None (depends on platform-api) |
|
|
| **mc1710** (root) | `src/main/java/` | MC 1.7.10 implementations: entities, GUI, packets, wrappers | Full Forge/MC |
|
|
| **gradle-plugins** | `gradle-plugins/` | TypeScript `.d.ts` generator from Java API sources | Gradle only |
|
|
| **API** (submodule) | `src/api/java/` | Scripting API interfaces (`IPlayer`, `ICustomNpc`, `IWorld`, etc.) | Git submodule — run `./gradlew updateAPI` |
|
|
|
|
**Dependency flow:** `platform-api` ← `core` ← `mc1710 (root src)`
|
|
|
|
## Architecture Pattern
|
|
- **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` → `IPlayer` (platform-api), mc1710 provides `PlayerWrapper`.
|
|
|
|
## Subsystem Location Map
|
|
|
|
| Subsystem | Primary Path(s) | Key Files |
|
|
|---|---|---|
|
|
| **NPC Entities** | `src/.../noppes/npcs/entity/` | `EntityNPCInterface.java`, `EntityCustomNpc.java` |
|
|
| **NPC Data** | `src/.../noppes/npcs/Data*.java` | `DataAI`, `DataDisplay`, `DataStats`, `DataAbilities`, `DataAdvanced` |
|
|
| **AI System** | `src/.../noppes/npcs/ai/` | 28 AI tasks (`EntityAI*.java`), `CombatHandler`, `pathfinder/`, `selector/`, `target/` |
|
|
| **Quest System** | `src/.../noppes/npcs/quests/` | `QuestItem`, `QuestKill`, `QuestLocation`, `QuestDialog`, `QuestManual` |
|
|
| **Quest Controller** | `src/.../noppes/npcs/controllers/` | `QuestController.java`, `PlayerQuestController.java` |
|
|
| **Dialog System** | `src/.../noppes/npcs/controllers/` | `DialogController.java` + data in `controllers/data/` |
|
|
| **Faction System** | `core/.../noppes/npcs/controllers/` | `FactionController.java`, `Faction.java` (migrated to core) |
|
|
| **Ability System** | `src/.../kamkeel/npcs/controllers/` | `AbilityController.java`, `EnergyController.java`, `TelegraphController.java` |
|
|
| **Ability Entities** | `src/.../kamkeel/npcs/entity/` | `EntityAbility*.java`, `EntityEnergy*.java` (13 entity types) |
|
|
| **Scripting Engine** | `src/.../noppes/npcs/controllers/` | `ScriptController.java`, `ScriptContainer.java`, `ScriptHookController.java` |
|
|
| **Scripting Wrappers** | `src/.../noppes/npcs/scripted/` | `ScriptWorld`, `ScriptBlock`, `NpcAPI`, `event/`, `entity/`, `item/`, `gui/` |
|
|
| **Economy/Auction** | `src/.../noppes/npcs/controllers/` | `AuctionController.java`, `MarketRegistry.java` |
|
|
| **Roles & Jobs** | `src/.../noppes/npcs/roles/` | `RoleTrader`, `RoleBank`, `RoleFollower`, `JobGuard`, `JobBard`, etc. |
|
|
| **Profile System** | `src/.../kamkeel/npcs/controllers/` | `ProfileController.java` |
|
|
| **Animation** | `src/.../noppes/npcs/controllers/` | `AnimationController.java` |
|
|
| **Commands** | `src/.../kamkeel/npcs/command/` | Hierarchical `/kam` system. `CommandKamkeel.java` is root. |
|
|
| **Config** | `src/.../noppes/npcs/config/` | `ConfigMain`, `ConfigClient`, `ConfigScript`, `ConfigMarket`, `ConfigEnergy`, etc. |
|
|
| **Blocks** | `src/.../noppes/npcs/blocks/` | 34 block types + `tiles/` |
|
|
| **Items** | `src/.../noppes/npcs/items/` | Weapons, linked items, scripted items |
|
|
| **Networking** | `src/.../kamkeel/npcs/network/` | `PacketHandler.java` + `SyncController.java` |
|
|
| **Mixins** | `src/.../noppes/npcs/mixin/` | Forge/MC mixins |
|
|
| **Client** | `src/.../noppes/npcs/client/` + `src/.../kamkeel/npcs/client/` | GUI, rendering, overlays |
|
|
| **Compat** | `src/.../noppes/npcs/compat/` | Cross-mod compatibility |
|
|
| **TypeScript Gen** | `gradle-plugins/src/` | Gradle plugin: Java API → `.d.ts` definitions |
|
|
|
|
## Core Migration Status
|
|
- **188 files** abstracted to `core/` + `platform-api/` out of ~1,810 total
|
|
- Migrated: Faction, Magic, Transport, Tag, GlobalData controllers + 60+ data classes
|
|
- See `SESSION_MEMORY.md` for migration roadmap and current strategy
|
|
|
|
## NEVER / DO NOT Rules
|
|
|
|
1. **NEVER touch script system for migration** — `ScriptHandler`, `ScriptContainer`, all `I*Script*` interfaces, Action framework. Deeply coupled, not yet planned.
|
|
2. **NEVER touch Ability.java or ability type classes for migration** — 30+ MC imports, deeply coupled to Entity/World/DamageSource.
|
|
3. **NEVER touch entity classes for migration** — extend MC Entity directly, must stay platform-side.
|
|
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**: 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 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
|
|
|
|
```bash
|
|
# First-time setup (pulls API submodule)
|
|
./gradlew updateAPI
|
|
|
|
# Build (includes TypeScript .d.ts generation)
|
|
./gradlew build
|
|
|
|
# Build without mixin embedding
|
|
./gradlew buildNoMixin
|
|
|
|
# Run game
|
|
./gradlew runClient
|
|
./gradlew runServer
|
|
|
|
# Run without Nashorn scripting engine
|
|
./gradlew runClientNoNashorn
|
|
./gradlew runServerNoNashorn
|
|
|
|
# Generate TypeScript definitions only
|
|
./gradlew generateTypeScriptDefinitions
|
|
|
|
# IDE setup (IntelliJ)
|
|
./gradlew genIntellijRuns
|
|
# Then add args: --tweakClass org.spongepowered.asm.launch.MixinTweaker --mixin customnpcs.mixins.json
|
|
```
|
|
|
|
**Build system**: GTNH Convention plugin + RetroFuturaGradle. Java 8 target (core/platform-api), Java 8 compile with JDK 8 (mc1710).
|
|
|
|
## Convention Summary
|
|
- Two root packages: `noppes.npcs.*` (original), `kamkeel.npcs.*` (additions)
|
|
- Controllers are singletons in `controllers/` packages — instantiated at server start
|
|
- Data classes use NBT serialization (`readNBT`/`writeNBT` pattern with `INBTCompound`)
|
|
- Commands: hierarchical under `/kam` — each subcommand is a `CommandKamkeelBase` subclass
|
|
- Script hooks: 154+ events across NPC, Player, Block, Item, Quest, Dialog, Ability, Auction, Animation
|
|
- Config: separate config classes per domain (`ConfigMain`, `ConfigScript`, `ConfigMarket`, etc.)
|
|
- Async saves: `CustomNPCsThreader` thread pool for controller persistence
|
|
- API submodule: `src/api/java/` — must `git submodule update --init --recursive` before build
|
|
|
|
## Key Reference Files
|
|
- `SESSION_MEMORY.md` — **Multi-version porting strategy**, owner's vision, corrected architecture, research synthesis
|
|
- `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
|
|
- `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
|