Telegraph API System

java/noppes/npcs/api/AbstractNpcAPI.java

@@ -30,6 +30,7 @@ import noppes.npcs.api.handler.IProfileHandler;
 import noppes.npcs.api.handler.IQuestHandler;
 import noppes.npcs.api.handler.IRecipeHandler;
 import noppes.npcs.api.handler.IScriptHookHandler;
+import noppes.npcs.api.handler.ITelegraphHandler;
 import noppes.npcs.api.handler.ITransportHandler;
 import noppes.npcs.api.handler.data.IAnimation;
 import noppes.npcs.api.handler.data.IFrame;
@@ -177,6 +178,17 @@ public abstract class AbstractNpcAPI {
 
     public abstract IAbilityHandler getAbilities();
 
+    public abstract ITelegraphHandler getTelegraphs();
+
+    /**
+     * Create a telegraph directly.
+     * Convenience method equivalent to getTelegraphs().create(type).
+     *
+     * @param type Type name: "circle", "ring", "line", "cone", "point"
+     * @return A new telegraph configuration
+     */
+    public abstract ITelegraph createTelegraph(String type);
+
     public abstract String[] getAllBiomeNames();
 
     public abstract ICustomNpc<?> createNPC(IWorld var1);

java/noppes/npcs/api/ITelegraph.java

@@ -0,0 +1,224 @@
+package noppes.npcs.api;
+
+import noppes.npcs.api.entity.IEntity;
+
+/**
+ * A telegraph is a visual warning indicator that displays on the ground.
+ * Telegraphs are commonly used to warn players of incoming attacks or mark areas of effect.
+ * <p>
+ * To create a telegraph:
+ * <pre>
+ * var telegraph = API.getTelegraphs().createCircle(5.0);
+ * telegraph.setDuration(60); // 3 seconds
+ * telegraph.setColor(0x80FF0000); // Semi-transparent red
+ * var instance = telegraph.spawn(world, x, y, z);
+ * </pre>
+ * <p>
+ * Telegraph types:
+ * <ul>
+ *     <li>CIRCLE - A filled circle with a radius</li>
+ *     <li>RING - A ring with inner and outer radius</li>
+ *     <li>LINE - A rectangular line in a direction</li>
+ *     <li>CONE - A cone/arc shape</li>
+ *     <li>POINT - A small point marker</li>
+ * </ul>
+ */
+public interface ITelegraph {
+
+    // ═══════════════════════════════════════════════════════════════════════════
+    // TYPE
+    // ═══════════════════════════════════════════════════════════════════════════
+
+    /**
+     * Get the telegraph type.
+     *
+     * @return Type name: "CIRCLE", "RING", "LINE", "CONE", or "POINT"
+     */
+    String getType();
+
+    /**
+     * Set the telegraph type.
+     *
+     * @param type Type name: "circle", "ring", "line", "cone", or "point" (case insensitive)
+     */
+    void setType(String type);
+
+    // ═══════════════════════════════════════════════════════════════════════════
+    // SHAPE PARAMETERS
+    // ═══════════════════════════════════════════════════════════════════════════
+
+    /**
+     * Get the radius (for CIRCLE and RING types).
+     */
+    float getRadius();
+
+    /**
+     * Set the radius (for CIRCLE and RING types).
+     */
+    void setRadius(float radius);
+
+    /**
+     * Get the inner radius (for RING type).
+     */
+    float getInnerRadius();
+
+    /**
+     * Set the inner radius (for RING type).
+     */
+    void setInnerRadius(float innerRadius);
+
+    /**
+     * Get the length (for LINE and CONE types).
+     */
+    float getLength();
+
+    /**
+     * Set the length (for LINE and CONE types).
+     */
+    void setLength(float length);
+
+    /**
+     * Get the width (for LINE type).
+     */
+    float getWidth();
+
+    /**
+     * Set the width (for LINE type).
+     */
+    void setWidth(float width);
+
+    /**
+     * Get the angle in degrees (for CONE type).
+     */
+    float getAngle();
+
+    /**
+     * Set the angle in degrees (for CONE type).
+     */
+    void setAngle(float angle);
+
+    // ═══════════════════════════════════════════════════════════════════════════
+    // TIMING
+    // ═══════════════════════════════════════════════════════════════════════════
+
+    /**
+     * Get the duration in ticks.
+     */
+    int getDuration();
+
+    /**
+     * Set the duration in ticks (20 ticks = 1 second).
+     */
+    void setDuration(int ticks);
+
+    // ═══════════════════════════════════════════════════════════════════════════
+    // COLORS
+    // ═══════════════════════════════════════════════════════════════════════════
+
+    /**
+     * Get the primary color in ARGB format.
+     */
+    int getColor();
+
+    /**
+     * Set the primary color in ARGB format.
+     * Example: 0x80FF0000 for semi-transparent red
+     */
+    void setColor(int argb);
+
+    /**
+     * Get the warning phase color in ARGB format.
+     */
+    int getWarningColor();
+
+    /**
+     * Set the warning phase color in ARGB format.
+     * This color is used during the final warning phase.
+     */
+    void setWarningColor(int argb);
+
+    /**
+     * Get the tick at which warning phase begins.
+     */
+    int getWarningStartTick();
+
+    /**
+     * Set the tick at which warning phase begins.
+     * When remaining ticks falls below this value, the telegraph uses the warning color.
+     */
+    void setWarningStartTick(int tick);
+
+    // ═══════════════════════════════════════════════════════════════════════════
+    // ANIMATION
+    // ═══════════════════════════════════════════════════════════════════════════
+
+    /**
+     * Check if pulsing animation is enabled.
+     */
+    boolean isAnimated();
+
+    /**
+     * Enable or disable pulsing animation.
+     */
+    void setAnimated(boolean animated);
+
+    // ═══════════════════════════════════════════════════════════════════════════
+    // POSITIONING
+    // ═══════════════════════════════════════════════════════════════════════════
+
+    /**
+     * Get the height offset from ground level.
+     */
+    float getHeightOffset();
+
+    /**
+     * Set the height offset from ground level.
+     * Default is 0.1 to prevent z-fighting with ground blocks.
+     */
+    void setHeightOffset(float offset);
+
+    // ═══════════════════════════════════════════════════════════════════════════
+    // SPAWN METHODS
+    // ═══════════════════════════════════════════════════════════════════════════
+
+    /**
+     * Spawn this telegraph at a position.
+     *
+     * @param world The world to spawn in
+     * @param x     X position
+     * @param y     Y position
+     * @param z     Z position
+     * @return The spawned telegraph instance
+     */
+    ITelegraphInstance spawn(IWorld world, double x, double y, double z);
+
+    /**
+     * Spawn this telegraph at a position with rotation.
+     *
+     * @param world The world to spawn in
+     * @param x     X position
+     * @param y     Y position
+     * @param z     Z position
+     * @param yaw   Rotation yaw (for directional telegraphs like LINE/CONE)
+     * @return The spawned telegraph instance
+     */
+    ITelegraphInstance spawn(IWorld world, double x, double y, double z, float yaw);
+
+    /**
+     * Spawn this telegraph following an entity.
+     * The telegraph will update its position to follow the entity.
+     *
+     * @param entity The entity to follow
+     * @return The spawned telegraph instance
+     */
+    ITelegraphInstance spawn(IEntity entity);
+
+    /**
+     * Spawn this telegraph following an entity with rotation.
+     *
+     * @param entity The entity to follow
+     * @param yaw    Rotation yaw
+     * @return The spawned telegraph instance
+     */
+    ITelegraphInstance spawn(IEntity entity, float yaw);
+}

java/noppes/npcs/api/ITelegraphInstance.java

@@ -0,0 +1,114 @@
+package noppes.npcs.api;
+
+import noppes.npcs.api.entity.IEntity;
+
+/**
+ * A runtime instance of an active telegraph in the world.
+ * Represents a spawned telegraph with position, timing, and control methods.
+ * <p>
+ * Instances are created when you call spawn() on an ITelegraph:
+ * <pre>
+ * var telegraph = API.getTelegraphs().createCircle(5.0);
+ * var instance = telegraph.spawn(world, x, y, z);
+ *
+ * // Later...
+ * instance.remove(); // Remove the telegraph early
+ * </pre>
+ */
+public interface ITelegraphInstance {
+
+    /**
+     * Get the unique instance ID.
+     */
+    String getInstanceId();
+
+    // ═══════════════════════════════════════════════════════════════════════════
+    // POSITION
+    // ═══════════════════════════════════════════════════════════════════════════
+
+    /**
+     * Get the current X position.
+     */
+    double getX();
+
+    /**
+     * Get the current Y position.
+     */
+    double getY();
+
+    /**
+     * Get the current Z position.
+     */
+    double getZ();
+
+    /**
+     * Get the rotation yaw.
+     */
+    float getYaw();
+
+    /**
+     * Set the position.
+     * Note: Only works for static telegraphs (not following an entity).
+     */
+    void setPosition(double x, double y, double z);
+
+    // ═══════════════════════════════════════════════════════════════════════════
+    // ENTITY FOLLOWING
+    // ═══════════════════════════════════════════════════════════════════════════
+
+    /**
+     * Make this telegraph follow an entity.
+     * The telegraph position will update each tick to match the entity.
+     */
+    void followEntity(IEntity entity);
+
+    /**
+     * Stop following any entity and fix the current position.
+     */
+    void stopFollowing();
+
+    /**
+     * Check if this telegraph is following an entity.
+     */
+    boolean isFollowing();
+
+    // ═══════════════════════════════════════════════════════════════════════════
+    // TIMING
+    // ═══════════════════════════════════════════════════════════════════════════
+
+    /**
+     * Get the remaining ticks before the telegraph expires.
+     */
+    int getRemainingTicks();
+
+    /**
+     * Get the total duration ticks.
+     */
+    int getTotalTicks();
+
+    /**
+     * Get the progress from 0.0 (just started) to 1.0 (finished).
+     */
+    float getProgress();
+
+    /**
+     * Check if the telegraph is in the warning phase.
+     */
+    boolean isWarning();
+
+    // ═══════════════════════════════════════════════════════════════════════════
+    // CONTROL
+    // ═══════════════════════════════════════════════════════════════════════════
+
+    /**
+     * Remove this telegraph immediately.
+     * Sends a removal packet to all clients tracking it.
+     */
+    void remove();
+
+    /**
+     * Lock the telegraph at its current position.
+     * Equivalent to calling stopFollowing().
+     */
+    void lockPosition();
+}

java/noppes/npcs/api/handler/ITelegraphHandler.java

@@ -0,0 +1,193 @@
+package noppes.npcs.api.handler;
+
+import noppes.npcs.api.ITelegraph;
+import noppes.npcs.api.ITelegraphInstance;
+import noppes.npcs.api.IWorld;
+import noppes.npcs.api.entity.IEntity;
+
+/**
+ * Handler for creating and managing telegraphs.
+ * Access via API.getTelegraphs()
+ * <p>
+ * Example usage:
+ * <pre>
+ * // Create a telegraph
+ * var telegraph = API.getTelegraphs().createCircle(5.0);
+ * telegraph.setDuration(60); // 3 seconds
+ * telegraph.setColor(0x80FF0000); // Semi-transparent red
+ *
+ * // Spawn it
+ * var instance = telegraph.spawn(world, x, y, z);
+ *
+ * // Or save as a preset for reuse
+ * API.getTelegraphs().save("myCircle", telegraph);
+ *
+ * // Load preset later
+ * var loaded = API.getTelegraphs().get("myCircle");
+ * loaded.spawn(world, x, y, z);
+ * </pre>
+ */
+public interface ITelegraphHandler {
+
+    // ═══════════════════════════════════════════════════════════════════════════
+    // FACTORY METHODS
+    // ═══════════════════════════════════════════════════════════════════════════
+
+    /**
+     * Create a circle telegraph.
+     *
+     * @param radius The radius of the circle
+     * @return A new telegraph configuration
+     */
+    ITelegraph createCircle(float radius);
+
+    /**
+     * Create a ring telegraph.
+     *
+     * @param outerRadius The outer radius
+     * @param innerRadius The inner radius
+     * @return A new telegraph configuration
+     */
+    ITelegraph createRing(float outerRadius, float innerRadius);
+
+    /**
+     * Create a line telegraph.
+     *
+     * @param length The length of the line
+     * @param width  The width of the line
+     * @return A new telegraph configuration
+     */
+    ITelegraph createLine(float length, float width);
+
+    /**
+     * Create a cone telegraph.
+     *
+     * @param length The length of the cone
+     * @param angle  The angle of the cone in degrees
+     * @return A new telegraph configuration
+     */
+    ITelegraph createCone(float length, float angle);
+
+    /**
+     * Create a point telegraph.
+     *
+     * @return A new telegraph configuration
+     */
+    ITelegraph createPoint();
+
+    /**
+     * Create a telegraph by type name.
+     *
+     * @param type Type name: "circle", "ring", "line", "cone", "point" (case insensitive)
+     * @return A new telegraph configuration, or null if type is invalid
+     */
+    ITelegraph create(String type);
+
+    // ═══════════════════════════════════════════════════════════════════════════
+    // SPAWN METHODS
+    // ═══════════════════════════════════════════════════════════════════════════
+
+    /**
+     * Spawn a telegraph at a position.
+     *
+     * @param telegraph The telegraph configuration
+     * @param world     The world
+     * @param x         X position
+     * @param y         Y position
+     * @param z         Z position
+     * @return The spawned instance
+     */
+    ITelegraphInstance spawn(ITelegraph telegraph, IWorld world, double x, double y, double z);
+
+    /**
+     * Spawn a telegraph at a position with rotation.
+     *
+     * @param telegraph The telegraph configuration
+     * @param world     The world
+     * @param x         X position
+     * @param y         Y position
+     * @param z         Z position
+     * @param yaw       Rotation yaw
+     * @return The spawned instance
+     */
+    ITelegraphInstance spawn(ITelegraph telegraph, IWorld world, double x, double y, double z, float yaw);
+
+    /**
+     * Spawn a telegraph following an entity.
+     *
+     * @param telegraph The telegraph configuration
+     * @param entity    The entity to follow
+     * @return The spawned instance
+     */
+    ITelegraphInstance spawn(ITelegraph telegraph, IEntity entity);
+
+    /**
+     * Spawn a telegraph following an entity with rotation.
+     *
+     * @param telegraph The telegraph configuration
+     * @param entity    The entity to follow
+     * @param yaw       Rotation yaw
+     * @return The spawned instance
+     */
+    ITelegraphInstance spawn(ITelegraph telegraph, IEntity entity, float yaw);
+
+    // ═══════════════════════════════════════════════════════════════════════════
+    // PRESET MANAGEMENT
+    // ═══════════════════════════════════════════════════════════════════════════
+
+    /**
+     * Get a saved telegraph preset by name.
+     *
+     * @param name The preset name
+     * @return The telegraph configuration, or null if not found
+     */
+    ITelegraph get(String name);
+
+    /**
+     * Save a telegraph as a preset.
+     *
+     * @param name      The name for the preset
+     * @param telegraph The telegraph configuration to save
+     */
+    void save(String name, ITelegraph telegraph);
+
+    /**
+     * Delete a saved preset.
+     *
+     * @param name The preset name
+     */
+    void delete(String name);
+
+    /**
+     * Check if a preset exists.
+     *
+     * @param name The preset name
+     * @return True if the preset exists
+     */
+    boolean has(String name);
+
+    /**
+     * Get all saved preset names.
+     *
+     * @return Array of preset names
+     */
+    String[] getSavedNames();
+
+    // ═══════════════════════════════════════════════════════════════════════════
+    // REMOVAL
+    // ═══════════════════════════════════════════════════════════════════════════
+
+    /**
+     * Remove an active telegraph by instance ID.
+     *
+     * @param instanceId The instance ID to remove
+     */
+    void remove(String instanceId);
+
+    /**
+     * Remove an active telegraph instance.
+     *
+     * @param instance The instance to remove
+     */
+    void remove(ITelegraphInstance instance);
+}