INDEXED PROJECT WITH AGENTS.md + IMPORTANT MODERM MIGRATION RESEARCH

AGENTS.md

@@ -0,0 +1,59 @@
+# Scripting API — `src/api/java/noppes/npcs/api`
+
+## Purpose
+Public Java interfaces that define the scripting API surface. Scripts (JS/Java) interact
+with the game exclusively through these interfaces — implementations live in `noppes.npcs.scripted`
+and `noppes.npcs.controllers.data`. This separation means API changes affect every scripter.
+
+## Package Layout
+| Package | Contents |
+|---------|----------|
+| `entity/` | Core entity types: `IEntity`, `IEntityLivingBase`, `IPlayer`, `ICustomNpc`, `IAnimatable`, plus energy projectile variants |
+| `entity/data/` | NPC visual data: `IModelData`, `IHitboxData`, `ITintData`, model scale/rotation |
+| `event/` | 20 event interfaces (`INpcEvent`, `IPlayerEvent`, `IBlockEvent`, `IQuestEvent`, etc.) containing nested hook event types |
+| `handler/` | Singletons and data managers: `ICloneHandler`, `IFactionHandler`, `IQuestHandler`, `IScriptHookHandler`, `IPlayerData`, etc. |
+| `handler/data/` | Data objects: `IQuest`, `IDialog`, `IFaction`, `IAnimation`, `IFrame`, `ILinkedItem`, `ICustomEffect`, `IParty`, etc. |
+| `item/` | Item wrappers: `IItemStack`, `IItemArmor`, `IItemLinked`, `IItemCustom` |
+| `ability/` | Ability system: `IAbility`, `IAbilityAction`, `IChainedAbility`, `IDataAbilities`, `IPlayerAbilityData` |
+| `gui/` | Custom GUI components: `ICustomGui`, `IButton`, `ILabel`, `ITextField`, `IScroll`, `IItemSlot` |
+| `overlay/` | Screen overlays: `ICustomOverlay`, `IOverlayLabel`, `IOverlayLine`, `IOverlayTexturedRect` |
+| `block/` | Scripted blocks: `IBlockScripted`, `ITextPlane` |
+| `roles/`, `jobs/` | NPC role/job interfaces: `IRoleTrader`, `IJobGuard`, etc. |
+| Root | Primitives: `IWorld`, `IPos`, `INbt`, `IBlock`, `ITimers`, `IDamageSource`, `IContainer`, `IParticle` |
+
+## Entity Hierarchy
+`IEntity<T>` → `IEntityLivingBase<T>` → `IEntityLiving<T>` → `ICustomNpc<T>`
+`IEntity<T>` → `IEntityLivingBase<T>` → `IPlayer<T>`
+Both `IPlayer` and `ICustomNpc` implement `IAnimatable`.
+
+## Event/Hook Pattern
+Every scriptable context has an event interface (e.g., `INpcEvent`) with nested inner interfaces
+for each hook. Each inner interface has a `@hookName` Javadoc tag naming the script function:
+```java
+/** @hookName damaged */
+@Cancelable
+interface DamagedEvent extends INpcEvent {
+    float getDamage();
+    void setDamage(float damage);
+    IEntity getSource();
+}
+```
+Scripts receive the event as a parameter: `function damaged(event) { event.setDamage(0); }`.
+Cancelable events can call `event.setCanceled(true)` to prevent default behavior.
+
+## Hook Registration (Addon API)
+`IScriptHookHandler` allows addons to register custom hooks with full metadata via
+`IHookDefinition` (hook name, event class FQN, param names, required imports, cancelable flag).
+Registered hooks appear in the script editor's hook list and get proper stub generation.
+
+## API Entry Point
+`AbstractNpcAPI` (accessed as `API` in scripts) provides global utilities: world access,
+item/entity creation, handler lookups, temp/stored data, NBT construction, overlay/GUI creation.
+
+## Design Rules
+- **Interface-only API**: No implementation classes. Scripters see only `I*` interfaces.
+- **Method overloads**: Provide both object-based (`IPos`) and primitive-based (`double x, y, z`) signatures.
+- **Generic type params**: Entity interfaces use `<T extends EntityXxx>` to expose `getMCEntity()` for advanced users.
+- **`@Deprecated` methods**: Keep for backward compatibility, add replacement alongside.
+- **`@hookName` tag**: Required on every event inner interface — drives editor hook list and stub generation.
+- **No runtime dependencies on editor**: API interfaces must never reference client/GUI classes.