Another MEGA COMMIT to Core Structure

platform-api/src/main/java/kamkeel/npcs/platform/annotation/ClientOnly.java

@@ -0,0 +1,22 @@
+package kamkeel.npcs.platform.annotation;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Marks code that should only exist on the physical client.
+ *
+ * This is a documentation-only annotation in core — it does NOT trigger
+ * class stripping like Forge's @SideOnly or Fabric's @Environment.
+ *
+ * Platform modules should use their native side annotations for actual stripping:
+ * - Forge 1.7.10/1.12: @SideOnly(Side.CLIENT)
+ * - Forge 1.16+: @OnlyIn(Dist.CLIENT)
+ * - Fabric: @Environment(EnvType.CLIENT)
+ */
+@Retention(RetentionPolicy.SOURCE)
+@Target({ElementType.TYPE, ElementType.METHOD, ElementType.FIELD, ElementType.CONSTRUCTOR})
+public @interface ClientOnly {
+}

platform-api/src/main/java/kamkeel/npcs/platform/annotation/ServerOnly.java

@@ -0,0 +1,17 @@
+package kamkeel.npcs.platform.annotation;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Marks code that should only exist on the dedicated server.
+ *
+ * This is a documentation-only annotation in core — it does NOT trigger
+ * class stripping. See {@link ClientOnly} for details.
+ */
+@Retention(RetentionPolicy.SOURCE)
+@Target({ElementType.TYPE, ElementType.METHOD, ElementType.FIELD, ElementType.CONSTRUCTOR})
+public @interface ServerOnly {
+}

platform-api/src/main/java/kamkeel/npcs/platform/entity/IPlatformDamageSource.java

@@ -0,0 +1,25 @@
+package kamkeel.npcs.platform.entity;
+
+/**
+ * Platform-independent damage source abstraction.
+ */
+public interface IPlatformDamageSource {
+
+    /**
+     * @return the damage type identifier (e.g., "player", "mob", "generic")
+     */
+    String getType();
+
+    /**
+     * @return the entity that caused this damage, or null if none (e.g., fall damage)
+     */
+    IPlatformEntity getSourceEntity();
+
+    /**
+     * Returns the underlying MC DamageSource object.
+     * Core code should NEVER call this.
+     *
+     * @return the raw MC DamageSource
+     */
+    Object getHandle();
+}

platform-api/src/main/java/kamkeel/npcs/platform/entity/IPlatformEntity.java

@@ -0,0 +1,58 @@
+package kamkeel.npcs.platform.entity;
+
+/**
+ * Platform-independent entity abstraction for core logic.
+ * Thin interface — only exposes what core actually needs.
+ *
+ * Each MC version provides an implementation wrapping the native Entity class.
+ * Use {@link #getHandle()} to retrieve the underlying MC object in platform code.
+ */
+public interface IPlatformEntity {
+
+    /**
+     * @return the entity's numeric ID in the world
+     */
+    int getEntityId();
+
+    /**
+     * @return the entity's UUID as a string
+     */
+    String getUniqueID();
+
+    // --- Position ---
+
+    double getX();
+
+    double getY();
+
+    double getZ();
+
+    float getYaw();
+
+    float getPitch();
+
+    void setPosition(double x, double y, double z);
+
+    // --- State ---
+
+    /**
+     * @return true if the entity exists and is not dead
+     */
+    boolean isAlive();
+
+    /**
+     * @return the dimension/world the entity is in
+     */
+    IPlatformWorld getWorld();
+
+    // --- Escape hatch ---
+
+    /**
+     * Returns the underlying MC entity object.
+     * Platform code can cast this to the version-specific Entity class.
+     * Core code should NEVER call this.
+     *
+     * @return the raw MC entity (e.g., net.minecraft.entity.Entity on 1.7.10)
+     */
+    Object getHandle();
+}

platform-api/src/main/java/kamkeel/npcs/platform/entity/IPlatformLiving.java

@@ -0,0 +1,22 @@
+package kamkeel.npcs.platform.entity;
+
+/**
+ * Platform-independent living entity abstraction.
+ * Extends {@link IPlatformEntity} with health and damage operations.
+ */
+public interface IPlatformLiving extends IPlatformEntity {
+
+    float getHealth();
+
+    void setHealth(float hp);
+
+    float getMaxHealth();
+
+    /**
+     * Deal damage to this entity.
+     *
+     * @param amount the damage amount
+     * @param source the damage source, or null for generic damage
+     */
+    void damage(float amount, IPlatformDamageSource source);
+}

platform-api/src/main/java/kamkeel/npcs/platform/entity/IPlatformPlayer.java

@@ -0,0 +1,36 @@
+package kamkeel.npcs.platform.entity;
+
+/**
+ * Platform-independent player abstraction.
+ * Extends {@link IPlatformLiving} with player-specific operations.
+ */
+public interface IPlatformPlayer extends IPlatformLiving {
+
+    /**
+     * @return the player's username
+     */
+    String getName();
+
+    /**
+     * @return the player's UUID as a string
+     */
+    @Override
+    String getUniqueID();
+
+    /**
+     * @return true if the player is a server operator
+     */
+    boolean isOp();
+
+    /**
+     * Send a chat message to this player.
+     *
+     * @param text plain text message
+     */
+    void sendMessage(String text);
+
+    /**
+     * @return the item currently held in the player's main hand, or null if empty
+     */
+    IPlatformStack getHeldItem();
+}

platform-api/src/main/java/kamkeel/npcs/platform/entity/IPlatformStack.java

@@ -0,0 +1,50 @@
+package kamkeel.npcs.platform.entity;
+
+import noppes.npcs.platform.nbt.INBTCompound;
+
+/**
+ * Platform-independent item stack abstraction.
+ */
+public interface IPlatformStack {
+
+    /**
+     * @return the item's registry ID (e.g., "minecraft:stone")
+     */
+    String getItemId();
+
+    int getCount();
+
+    void setCount(int count);
+
+    /**
+     * @return the item's damage/metadata value
+     */
+    int getDamage();
+
+    void setDamage(int dmg);
+
+    /**
+     * @return the stack's NBT tag compound, or null if none
+     */
+    INBTCompound getTag();
+
+    void setTag(INBTCompound tag);
+
+    /**
+     * @return true if this stack is empty (null item or count <= 0)
+     */
+    boolean isEmpty();
+
+    /**
+     * @return a deep copy of this stack
+     */
+    IPlatformStack copy();
+
+    /**
+     * Returns the underlying MC ItemStack object.
+     * Core code should NEVER call this.
+     *
+     * @return the raw MC ItemStack
+     */
+    Object getHandle();
+}

platform-api/src/main/java/kamkeel/npcs/platform/entity/IPlatformWorld.java

@@ -0,0 +1,33 @@
+package kamkeel.npcs.platform.entity;
+
+/**
+ * Platform-independent world abstraction.
+ */
+public interface IPlatformWorld {
+
+    /**
+     * @return the dimension ID (e.g., 0 for overworld, -1 for nether)
+     */
+    int getDimensionId();
+
+    /**
+     * @return true if this is a client-side world
+     */
+    boolean isClient();
+
+    /**
+     * Look up an entity by its numeric ID.
+     *
+     * @param id the entity ID
+     * @return the entity, or null if not found
+     */
+    IPlatformEntity getEntityById(int id);
+
+    /**
+     * Returns the underlying MC World object.
+     * Core code should NEVER call this.
+     *
+     * @return the raw MC World
+     */
+    Object getHandle();
+}

platform-api/src/main/java/noppes/npcs/api/ability/data/IEnergyAnchorData.java

@@ -0,0 +1,40 @@
+package noppes.npcs.api.ability.data;
+
+/**
+ * Configuration for the anchor point of an energy ability projectile.
+ * Controls where the projectile spawns relative to the caster.
+ */
+public interface IEnergyAnchorData {
+    /** @return Anchor point ordinal (0=FRONT, 1=CENTER, 2=RIGHT_HAND, 3=LEFT_HAND, 4=ABOVE_HEAD, 5=CHEST, 6=EYE). */
+    int getAnchor();
+
+    /**
+     * Set the anchor point.
+     * @param anchor Anchor ordinal (0=FRONT, 1=CENTER, 2=RIGHT_HAND, 3=LEFT_HAND, 4=ABOVE_HEAD, 5=CHEST, 6=EYE)
+     */
+    void setAnchor(int anchor);
+
+    /** @return X offset from the anchor point (positive = right). */
+    float getAnchorOffsetX();
+
+    /** @param anchorOffsetX X offset from anchor (positive = right). */
+    void setAnchorOffsetX(float anchorOffsetX);
+
+    /** @return Y offset from the anchor point (positive = up). */
+    float getAnchorOffsetY();
+
+    /** @param anchorOffsetY Y offset from anchor (positive = up). */
+    void setAnchorOffsetY(float anchorOffsetY);
+
+    /** @return Z offset from the anchor point (positive = forward). */
+    float getAnchorOffsetZ();
+
+    /** @param anchorOffsetZ Z offset from anchor (positive = forward). */
+    void setAnchorOffsetZ(float anchorOffsetZ);
+
+    /** @return Whether the projectile launches from the anchor position instead of the default eye/look-vector position. */
+    boolean getLaunchFromAnchor();
+
+    /** @param launchFromAnchor When true, the projectile launches from its anchor position; when false, it snaps to the default eye/look-vector position. */
+    void setLaunchFromAnchor(boolean launchFromAnchor);
+}

platform-api/src/main/java/noppes/npcs/api/ability/data/IEnergyCombatData.java

@@ -0,0 +1,43 @@
+package noppes.npcs.api.ability.data;
+
+/**
+ * Combat properties for energy ability projectiles.
+ * Controls damage, knockback, and explosion behavior.
+ */
+public interface IEnergyCombatData {
+    /** @return Base damage dealt on hit. */
+    float getDamage();
+
+    /** @param damage Base damage on hit. */
+    void setDamage(float damage);
+
+    /** @return Horizontal knockback strength applied on hit. */
+    float getKnockback();
+
+    /** @param knockback Horizontal knockback strength. */
+    void setKnockback(float knockback);
+
+    /** @return Vertical knockback strength applied on hit. */
+    float getKnockbackUp();
+
+    /** @param knockbackUp Vertical knockback strength. */
+    void setKnockbackUp(float knockbackUp);
+
+    /** @return Whether the projectile explodes on impact. */
+    boolean isExplosive();
+
+    /** @param explosive Whether to explode on impact. */
+    void setExplosive(boolean explosive);
+
+    /** @return Explosion radius in blocks. */
+    float getExplosionRadius();
+
+    /** @param explosionRadius Explosion radius in blocks. */
+    void setExplosionRadius(float explosionRadius);
+
+    /** @return Damage falloff multiplier over distance (0.0-1.0). */
+    float getExplosionDamageFalloff();
+
+    /** @param explosionDamageFalloff Damage falloff multiplier (0.0-1.0). */
+    void setExplosionDamageFalloff(float explosionDamageFalloff);
+}

platform-api/src/main/java/noppes/npcs/api/ability/data/IEnergyDisplayData.java

@@ -0,0 +1,49 @@
+package noppes.npcs.api.ability.data;
+
+/**
+ * Visual display properties for energy ability projectiles.
+ * Controls colors, transparency, and rotation speed.
+ */
+public interface IEnergyDisplayData {
+    /** @return Inner (core) color as a packed RGB integer. */
+    int getInnerColor();
+
+    /** @param innerColor Inner color as a packed RGB integer. */
+    void setInnerColor(int innerColor);
+
+    /** @return Outer (glow) color as a packed RGB integer. */
+    int getOuterColor();
+
+    /** @param outerColor Outer color as a packed RGB integer. */
+    void setOuterColor(int outerColor);
+
+    /** @return Whether the outer color layer is rendered. */
+    boolean isOuterColorEnabled();
+
+    /** @param outerColorEnabled Whether to render the outer color layer. */
+    void setOuterColorEnabled(boolean outerColorEnabled);
+
+    /** @return Width of the outer color layer relative to the projectile size. */
+    float getOuterColorWidth();
+
+    /** @param outerColorWidth Outer color layer width. */
+    void setOuterColorWidth(float outerColorWidth);
+
+    /** @return Alpha (opacity) of the outer color layer (0.0-1.0). */
+    float getOuterColorAlpha();
+
+    /** @param outerColorAlpha Outer color opacity (0.0-1.0). */
+    void setOuterColorAlpha(float outerColorAlpha);
+
+    /** @return Alpha (opacity) of the inner color layer (0.0-1.0). */
+    float getInnerAlpha();
+
+    /** @param innerAlpha Inner color opacity (0.0-1.0). */
+    void setInnerAlpha(float innerAlpha);
+
+    /** @return Visual rotation speed in degrees per tick. */
+    float getRotationSpeed();
+
+    /** @param rotationSpeed Rotation speed in degrees per tick. */
+    void setRotationSpeed(float rotationSpeed);
+}

platform-api/src/main/java/noppes/npcs/api/ability/data/IEnergyHomingData.java

@@ -0,0 +1,31 @@
+package noppes.npcs.api.ability.data;
+
+/**
+ * Homing and speed properties for energy ability projectiles.
+ * Controls projectile velocity and target-seeking behavior.
+ */
+public interface IEnergyHomingData {
+    /** @return Projectile travel speed in blocks per tick. */
+    float getSpeed();
+
+    /** @param speed Travel speed in blocks per tick. */
+    void setSpeed(float speed);
+
+    /** @return Whether the projectile tracks its target. */
+    boolean isHoming();
+
+    /** @param homing Whether to track the target. */
+    void setHoming(boolean homing);
+
+    /** @return Homing turn strength (higher = tighter turns). */
+    float getHomingStrength();
+
+    /** @param homingStrength Homing turn strength. */
+    void setHomingStrength(float homingStrength);
+
+    /** @return Maximum distance at which homing activates, in blocks. */
+    float getHomingRange();
+
+    /** @param homingRange Maximum homing activation range in blocks. */
+    void setHomingRange(float homingRange);
+}

platform-api/src/main/java/noppes/npcs/api/ability/data/IEnergyLifespanData.java

@@ -0,0 +1,19 @@
+package noppes.npcs.api.ability.data;
+
+/**
+ * Lifespan properties for energy ability projectiles.
+ * Controls how far and how long a projectile can travel before expiring.
+ */
+public interface IEnergyLifespanData {
+    /** @return Maximum travel distance in blocks before the projectile expires. */
+    float getMaxDistance();
+
+    /** @param maxDistance Maximum travel distance in blocks. */
+    void setMaxDistance(float maxDistance);
+
+    /** @return Maximum lifetime in ticks before the projectile expires. */
+    int getMaxLifetime();
+
+    /** @param maxLifetime Maximum lifetime in ticks. */
+    void setMaxLifetime(int maxLifetime);
+}

platform-api/src/main/java/noppes/npcs/api/ability/data/IEnergyLightningData.java

@@ -0,0 +1,31 @@
+package noppes.npcs.api.ability.data;
+
+/**
+ * Lightning visual effect properties for energy ability projectiles.
+ * Controls the electric arc effect rendered around the projectile.
+ */
+public interface IEnergyLightningData {
+    /** @return Whether the lightning visual effect is enabled. */
+    boolean isLightningEffect();
+
+    /** @param lightningEffect Whether to enable the lightning effect. */
+    void setLightningEffect(boolean lightningEffect);
+
+    /** @return Density of lightning arcs (higher = more arcs). */
+    float getLightningDensity();
+
+    /** @param lightningDensity Lightning arc density. */
+    void setLightningDensity(float lightningDensity);
+
+    /** @return Radius of the lightning effect around the projectile, in blocks. */
+    float getLightningRadius();
+
+    /** @param lightningRadius Lightning effect radius in blocks. */
+    void setLightningRadius(float lightningRadius);
+
+    /** @return Fade-out time for lightning arcs in ticks. */
+    int getLightningFadeTime();
+
+    /** @param lightningFadeTime Fade-out time in ticks. */
+    void setLightningFadeTime(int lightningFadeTime);
+}

platform-api/src/main/java/noppes/npcs/api/handler/data/IPlayerEffect.java

@@ -0,0 +1,37 @@
+package noppes.npcs.api.handler.data;
+
+/**
+ * Represents an active custom effect instance on a player.
+ * <p>
+ * Note: performEffect(IPlayer) is omitted from the platform API
+ * because IPlayer depends on MC entity types.
+ */
+public interface IPlayerEffect {
+
+    /** Removes this effect from the player. */
+    void kill();
+
+    /** @return the custom effect ID. */
+    int getId();
+
+    /** @return the remaining duration in seconds (-100 for infinite). */
+    int getDuration();
+
+    /** @param duration the remaining duration in seconds (-100 for infinite). */
+    void setDuration(int duration);
+
+    /** @return the effect level/amplifier. */
+    byte getLevel();
+
+    /** @param level the effect level/amplifier. */
+    void setLevel(byte level);
+
+    /** @return the display name of the effect. */
+    String getName();
+
+    /** @return the effect source index (0: CNPC+, 1: DBC Addon). */
+    int getIndex();
+
+    /** @param index the effect source index (0: CNPC+, 1: DBC Addon). */
+    void setIndex(int index);
+}

platform-api/src/main/java/noppes/npcs/api/handler/data/ISlot.java

@@ -0,0 +1,29 @@
+package noppes.npcs.api.handler.data;
+
+import noppes.npcs.platform.nbt.INBTCompound;
+
+import java.util.Map;
+
+public interface ISlot {
+    int getId();
+
+    String getName();
+
+    void setName(String name);
+
+    long getLastLoaded();
+
+    void setLastLoaded(long time);
+
+    boolean isTemporary();
+
+    void setTemporary(boolean temporary);
+
+    Map<String, INBTCompound> getComponents();
+
+    void setComponentData(String key, INBTCompound data);
+
+    INBTCompound getComponentData(String key);
+
+    INBTCompound toNBT();
+}

platform-api/src/main/java/noppes/npcs/platform/PlatformService.java

@@ -1,5 +1,11 @@
 package noppes.npcs.platform;
 
+import kamkeel.npcs.platform.entity.IPlatformDamageSource;
+import kamkeel.npcs.platform.entity.IPlatformEntity;
+import kamkeel.npcs.platform.entity.IPlatformLiving;
+import kamkeel.npcs.platform.entity.IPlatformPlayer;
+import kamkeel.npcs.platform.entity.IPlatformStack;
+import kamkeel.npcs.platform.entity.IPlatformWorld;
 import noppes.npcs.platform.nbt.INBTCompound;
 import noppes.npcs.platform.nbt.INBTList;
 import noppes.npcs.platform.nbt.NBTFactory;
@@ -93,4 +99,64 @@ public interface PlatformService {
      * Logs at DEBUG level.
      */
     void logDebug(String message);
+
+    // --- Entity Wrapping ---
+
+    /**
+     * Wraps a raw MC player entity into a platform-independent player.
+     *
+     * @param mcPlayer the MC player object (e.g., EntityPlayerMP on 1.7.10)
+     * @return a platform player wrapper
+     */
+    IPlatformPlayer wrapPlayer(Object mcPlayer);
+
+    /**
+     * Wraps a raw MC entity into a platform-independent entity.
+     *
+     * @param mcEntity the MC entity object
+     * @return a platform entity wrapper
+     */
+    IPlatformEntity wrapEntity(Object mcEntity);
+
+    /**
+     * Wraps a raw MC living entity into a platform-independent living entity.
+     *
+     * @param mcLiving the MC living entity object (e.g., EntityLivingBase on 1.7.10)
+     * @return a platform living wrapper
+     */
+    IPlatformLiving wrapLiving(Object mcLiving);
+
+    /**
+     * Wraps a raw MC item stack into a platform-independent stack.
+     *
+     * @param mcStack the MC ItemStack object
+     * @return a platform stack wrapper
+     */
+    IPlatformStack wrapStack(Object mcStack);
+
+    /**
+     * Wraps a raw MC world into a platform-independent world.
+     *
+     * @param mcWorld the MC World object
+     * @return a platform world wrapper
+     */
+    IPlatformWorld wrapWorld(Object mcWorld);
+
+    /**
+     * Wraps a raw MC damage source into a platform-independent damage source.
+     *
+     * @param mcSource the MC DamageSource object
+     * @return a platform damage source wrapper
+     */
+    IPlatformDamageSource wrapDamageSource(Object mcSource);
+
+    // --- Scheduling ---
+
+    /**
+     * Runs a task on the main server thread.
+     * Safe to call from any thread.
+     *
+     * @param task the task to run
+     */
+    void runOnMainThread(Runnable task);
 }