diff --git a/java/noppes/npcs/api/handler/IActionManager.java b/java/noppes/npcs/api/handler/IActionManager.java index dcac137..7da42c2 100644 --- a/java/noppes/npcs/api/handler/IActionManager.java +++ b/java/noppes/npcs/api/handler/IActionManager.java @@ -1,80 +1,172 @@ package noppes.npcs.api.handler; import noppes.npcs.api.handler.data.IAction; + import java.util.Queue; import java.util.function.Consumer; +import java.util.function.Supplier; /** - * Interface for managing and scheduling actions. - * Provides methods to create, start, stop, and queue actions. + * Manages a queue of {@link IAction} instances, allowing scheduling of delayed, + * repeating, or conditional “tasks” for NPC scripting. */ public interface IActionManager { + /** - * Creates a new IAction instance with the specified parameters. + * Create a new action instance without immediately scheduling it. * - * @param name the name of the action. - * @param maxDuration the maximum duration (in ticks) for the action. - * @param startAfterTicks the delay in ticks before the action starts. - * @param action the consumer defining the action's behavior. - * @return a new IAction instance. + * @param name a unique name for this action + * @param maxDuration the maximum lifetime of the action in ticks + * @param startAfterTicks number of ticks to wait before the first run + * @param action logic to execute each time the action “fires” + * @return a fresh {@link IAction} object */ IAction create(String name, int maxDuration, int startAfterTicks, Consumer action); /** - * Starts the action manager, enabling the processing of scheduled actions. + * Begin processing scheduled actions. Must be called once. */ void start(); /** - * Stops the action manager, halting the processing of scheduled actions. + * Halt processing of actions. Queued actions remain but will not run until + * {@link #start()} is called again. */ void stop(); /** - * Schedules an action by adding it to the action queue. + * Schedule an existing action for execution. * - * @param action the action to be scheduled. + * @param action the action to enqueue */ void scheduleAction(IAction action); /** - * Creates and schedules an action with the given parameters. + * Convenience for {@link #create(String, int, int, Consumer)} + enqueue. * - * @param name the name of the action. - * @param maxDuration the maximum duration (in ticks) for the action. - * @param startAfterTicks the delay in ticks before the action starts. - * @param action the consumer defining the action's behavior. + * @param name a unique name for this action + * @param maxDuration the maximum lifetime of the action in ticks + * @param startAfterTicks number of ticks to wait before the first run + * @param action logic to execute each time the action “fires” */ void scheduleAction(String name, int maxDuration, int startAfterTicks, Consumer action); /** - * Inserts an action into the action queue at the specified index. + * Insert an action at a specific position in the queue. * - * @param index the position in the queue where the action should be added. - * @param action the action to insert. + * @param index zero-based queue position to insert at + * @param action the action to insert */ void scheduleActionAt(int index, IAction action); - /** - * Retrieves the index of the specified action in the action queue. + * Get the zero-based position of an action in the queue. * - * @param action the action whose index is to be determined. - * @return the index of the action in the queue, or -1 if not found. + * @param action the action to look up + * @return its index, or -1 if not found */ int getIndex(IAction action); /** - * Gets the current action (the one at the head of the queue). + * Peek at the next action to run (the head of the queue). * - * @return the current action, or null if the queue is empty. + * @return the current head action, or null if queue is empty */ IAction getCurrentAction(); /** - * Returns the queue of scheduled actions. + * Retrieve the entire action queue. * - * @return the action queue. + * @return live reference to the internal {@link Queue} of actions */ Queue getActionQueue(); + + /** + * Schedule a “conditional” action: every {@code checkIntervalTicks}, evaluate + * the predicate, and as soon as it returns true, fire the action and remove it. + * + * @param name a unique name for this conditional action + * @param checkIntervalTicks number of ticks between each predicate check + * @param predicate no-arg boolean supplier deciding when to fire + * @param action logic to execute once when predicate first becomes true + */ + void scheduleConditionalAction(String name, int checkIntervalTicks, Supplier predicate, Consumer action); + + /** + * Schedule a conditional action that gives up after at most maxChecks attempts. + * + * @param name unique name + * @param checkIntervalTicks ticks between predicate tests + * @param predicate supplier returning true when it should fire + * @param task logic to run once when predicate first becomes true + * @param maxChecks maximum times to test predicate before auto‐cancelling + */ + void scheduleConditionalAction(String name, int checkIntervalTicks, Supplier predicate, Consumer task, int maxChecks); + + /** + * Cancel (remove) the first queued action with the given name. + * + * @param name the name assigned when scheduling + * @return true if one was found and removed, false otherwise + */ + boolean cancelAction(String name); + + /** + * Remove every scheduled action immediately. + */ + void clear(); + + /** + * Convenience: create & enqueue a normal repeating task. + */ + default void addTask(String name, int maxDuration, int startAfterTicks, Consumer task) { + scheduleAction(name, maxDuration, startAfterTicks, task); + } + + /** + * Convenience: create & enqueue a task that will fire exactly once + * after the given delay, and then auto‐complete. + * + * @param name a unique name for this action + * @param startAfterTicks delay before it runs (in ticks) + * @param task logic to execute once + */ + default void addSingleTask(String name, int startAfterTicks, Consumer task) { + IAction action = create(name, 1, startAfterTicks, act -> { + task.accept(act); + act.markDone(); + }); + // force it to fire on the very next tick once the delay expires + action.setUpdateEveryXTick(1); + scheduleAction(action); + } + + /** + * Same as above, but fires immediately (no delay). + */ + default void addSingleTask(String name, Consumer task) { + addSingleTask(name, 0, task); + } + + + /** + * Convenience: create & enqueue a conditional task that re-checks forever. + */ + default void addConditionalTask(String name, + int checkIntervalTicks, + Supplier predicate, + Consumer task) { + scheduleConditionalAction(name, checkIntervalTicks, predicate, task); + } + + /** + * Convenience: create & enqueue a conditional task that gives up after maxChecks. + */ + default void addConditionalTask(String name, + int checkIntervalTicks, + Supplier predicate, + Consumer task, + int maxChecks) { + scheduleConditionalAction(name, checkIntervalTicks, predicate, task, maxChecks); + } } diff --git a/java/noppes/npcs/api/handler/data/IAction.java b/java/noppes/npcs/api/handler/data/IAction.java index e268585..ef6d625 100644 --- a/java/noppes/npcs/api/handler/data/IAction.java +++ b/java/noppes/npcs/api/handler/data/IAction.java @@ -3,113 +3,120 @@ package noppes.npcs.api.handler.data; import java.util.function.Consumer; /** - * Represents an action that can be executed over a period of time. - * Provides methods to query its state, update data, and chain scheduling. + * Represents a single “task” that can be executed over multiple ticks, + * supports delayed start, limited duration, repeating intervals, data storage, + * and chaining to neighboring tasks. */ public interface IAction { + /** - * Gets the number of times this action has been executed. - * - * @return the execution count. + * @return how many times this action’s {@code action.accept(this)} callback has run */ int getCount(); /** - * Gets the elapsed duration (in ticks) since the action began. - * - * @return the duration in ticks. + * @return how many ticks have elapsed since this action actually began (excluding start delay) */ int getDuration(); /** - * Gets the name of this action. - * - * @return the action name. + * @return the name given at creation/scheduling time */ String getName(); /** - * Gets the maximum duration (in ticks) that this action is allowed to run. - * - * @return the maximum duration in ticks. + * @return the maximum number of ticks this action is allowed to run before auto-terminating */ int getMaxDuration(); /** - * Marks the action as completed or not. + * Mark this action as complete. Once done, it will be removed on the next tick. */ void markDone(); /** - * Checks if the action has been marked as completed. - * - * @return true if the action is done, false otherwise. + * @return true if {@link #markDone()} was called (or maxDuration reached) */ boolean isDone(); /** - * Retrieves the data associated with the specified key. + * Retrieve arbitrary per-action data. * - * @param key the key of the data. - * @return the associated data, or null if not present. + * @param key a string key + * @return the stored value, or null if not set */ Object getData(String key); /** - * Stores data with the specified key. + * Store arbitrary per-action data. * - * @param key the key under which the data is stored. - * @param value the data to store. + * @param key a string key + * @param value any object to associate with this action */ void addData(String key, Object value); /** - * Gets the interval (in ticks) between each update of this action. - * - * @return the number of ticks between updates. + * @return how many ticks between each invocation of the action callback */ int getUpdateEveryXTick(); /** - * Sets the update frequency in ticks. + * Set how many ticks between each invocation of the action callback. * - * @param X the number of ticks between each update. + * @param X tick interval (e.g. 1 = every tick, 20 = once per second) */ void setUpdateEveryXTick(int X); /** - * Gets the number of ticks to wait before starting the action. - * - * @return the delay in ticks before the action starts. + * @return how many ticks remain before the action begins (initial delay) */ int getStartAfterTicks(); /** - * Creates a new IAction instance with the given parameters. + * Factory helper so that from within one action you can create + * new IAction instances without referencing the manager directly. * - * @param name the name of the action. - * @param maxDuration the maximum duration (in ticks) the action can run. - * @param startAfterTicks the delay in ticks before the action starts. - * @param action the consumer defining the action's behavior. - * @return a new IAction instance. + * @param name a unique name for the new action + * @param maxDuration its maximum lifetime + * @param startAfterTicks initial delay in ticks + * @param action callback logic + * @return a new IAction */ IAction create(String name, int maxDuration, int startAfterTicks, Consumer action); + /** + * @return the next action in the queue (or null if none or at end) + */ IAction getNext(); + /** + * @return the previous action in the queue (or null if none or at front) + */ IAction getPrevious(); /** - * Schedules another action to be executed immediately after this action. + * Enqueue another action immediately after this one. * - * @param after the action to schedule after this one. + * @param after the action to run next */ void scheduleAfter(IAction after); /** - * Schedules an action to be executed before current action, which pauses current until before finishes. + * Enqueue another action immediately before this one (pausing this one until done). * - * @param before the action to schedule before this one. + * @param before the action to run prior */ void scheduleBefore(IAction before); + + /** + * Note: Only for Conditional Actions + * @return how many times this conditional action has tested its predicate + */ + int getCheckCount(); + + /** + * Note: Only for Conditional Actions + * @return the maximum number of checks before auto‐expiring, or –1 if unlimited + */ + int getMaxChecks(); }