A lot of GOOD API DOCUMENTATION

This commit is contained in:
Kam committed 2026-03-09 16:20:07 -04:00
1 parent a6c55ca331
commit 319e774518
131 files changed
+3363 -175

No files matched your search

@@ -12,6 +12,7 @@ public interface IAbility extends IAbilityAction {
/**
* Get the unique ID (UUID for custom abilities, registry key for built-in).
* This is the stable reference that never changes after creation.
* @return the unique ability ID
*/
String getId();
@@ -34,6 +35,7 @@ public interface IAbility extends IAbilityAction {
/**
* Get the display name (cosmetic). Falls back to getName() if not set.
* @return the display name
*/
String getDisplayName();
@@ -45,6 +47,7 @@ public interface IAbility extends IAbilityAction {
/**
* Get the type ID of this ability (e.g., "cnpc:slam", "cnpc:beam").
* @return the type ID
*/
String getTypeId();
@@ -106,6 +109,7 @@ public interface IAbility extends IAbilityAction {
/**
* Get the wind-up time in ticks (telegraph phase).
* @return wind-up time in ticks
*/
int getWindUpTicks();
@@ -117,6 +121,7 @@ public interface IAbility extends IAbilityAction {
/**
* Get the dazed time in ticks (stun after interrupt during WINDUP).
* @return dazed time in ticks
*/
int getDazedTicks();
@@ -128,6 +133,7 @@ public interface IAbility extends IAbilityAction {
/**
* Check if this ability can be interrupted by damage.
* @return true if interruptible
*/
boolean isInterruptible();
@@ -139,6 +145,7 @@ public interface IAbility extends IAbilityAction {
/**
* Check if this ability ignores target invulnerability frames (hurt resistance).
* @return true if ignoring invulnerability frames
*/
boolean isIgnoreIFrames();
@@ -193,6 +200,7 @@ public interface IAbility extends IAbilityAction {
/**
* Get track speed for TRACK rotation mode (blocks/second).
* 0 = instant tracking. Comparable to player sprint speed (~5.6 blocks/sec).
* @return track speed in blocks/second
*/
float getTrackSpeedValue();
@@ -205,36 +213,43 @@ public interface IAbility extends IAbilityAction {
/**
* Check if movement (pathfinding/motion) is locked during the WINDUP phase.
* @return true if movement is locked during windup
*/
boolean isMovementLockedDuringWindup();
/**
* Check if movement (pathfinding/motion) is locked during the ACTIVE phase.
* @return true if movement is locked during active phase
*/
boolean isMovementLockedDuringActive();
/**
* Check if rotation (yaw/pitch) is locked during the WINDUP phase.
* @return true if rotation is locked during windup
*/
boolean isRotationLockedDuringWindup();
/**
* Check if rotation (yaw/pitch) is locked during the ACTIVE phase.
* @return true if rotation is locked during active phase
*/
boolean isRotationLockedDuringActive();
/**
* Check if this ability is currently being executed.
* @return true if currently executing
*/
boolean isExecuting();
/**
* Get the current execution phase (0=IDLE, 1=WINDUP, 2=ACTIVE, 3=DAZED, 4=BURST_DELAY).
* @return the current phase ordinal
*/
int getPhaseInt();
/**
* Get the current tick within the current phase.
* @return the current tick within the phase
*/
int getCurrentTick();
@@ -254,6 +269,7 @@ public interface IAbility extends IAbilityAction {
/**
* Check if this ability ignores cooldowns.
* @return true if ignoring cooldowns
*/
boolean isIgnoreCooldown();
@@ -266,6 +282,7 @@ public interface IAbility extends IAbilityAction {
/**
* Check if this ability uses per-ability cooldown instead of global cooldown.
* When true, using this ability only puts THIS ability on cooldown, not all abilities.
* @return true if using per-ability cooldown
*/
boolean isPerAbilityCooldown();
@@ -277,6 +294,7 @@ public interface IAbility extends IAbilityAction {
/**
* Get this ability's data as NBT.
* @return the ability's NBT data
*/
INbt getNbt();
@@ -322,12 +340,14 @@ public interface IAbility extends IAbilityAction {
/**
* Check if this ability is toggleable (has at least 1 toggle state).
* @return true if toggleable
*/
boolean isToggleable();
/**
* Get the number of toggle states.
* 0 = not toggleable, 1 = binary on/off, 2+ = multi-state cycling.
* @return number of toggle states
*/
int getToggleStates();
@@ -17,17 +17,25 @@ public interface IAbilityHandler {
/**
* Check if an ability type is registered.
*
* @param typeId the type ID to check
* @return true if registered
*/
boolean hasType(String typeId);
/**
* Get all registered ability type IDs.
*
* @return array of registered type IDs
*/
String[] getTypes();
/**
* Create a new ability of the given type.
* Returns null if the type is not registered.
*
* @param typeId the type ID
* @return the new ability, or null
*/
IAbility create(String typeId);
@@ -8,11 +8,13 @@ public interface ICustomAbility extends IAbility {
/**
* Get the duration in ticks for instant mode (non-toggle).
* @return duration in ticks
*/
int getDurationTicks();
/**
* Set the duration in ticks for instant mode.
* @param ticks duration in ticks
*/
void setDurationTicks(int ticks);
@@ -43,72 +45,86 @@ public interface ICustomAbility extends IAbility {
/**
* Get how many ticks the telegraph persists during the active phase.
* When syncTelegraphWithDuration is true, this returns the duration ticks.
* @return telegraph active ticks
*/
int getTelegraphActiveTicks();
/**
* Set how many ticks the telegraph persists during the active phase.
* Only used when syncTelegraphWithDuration is false.
* @param ticks telegraph active ticks
*/
void setTelegraphActiveTicks(int ticks);
/**
* Whether telegraph active ticks are synced to the ability duration.
* @return true if synced
*/
boolean isSyncTelegraphWithDuration();
/**
* Set whether telegraph active ticks should sync to the ability duration.
* @param sync whether to sync
*/
void setSyncTelegraphWithDuration(boolean sync);
/**
* Get the telegraph radius (used by CIRCLE, RING, SQUARE shapes).
* @return the telegraph radius
*/
float getTelegraphRadius();
/**
* Set the telegraph radius.
* @param radius the telegraph radius
*/
void setTelegraphRadius(float radius);
/**
* Get the telegraph inner radius (used by RING, CONE shapes).
* @return the inner radius
*/
float getTelegraphInnerRadius();
/**
* Set the telegraph inner radius.
* @param innerRadius the inner radius
*/
void setTelegraphInnerRadius(float innerRadius);
/**
* Get the telegraph length (used by LINE, CONE shapes).
* @return the telegraph length
*/
float getTelegraphLength();
/**
* Set the telegraph length.
* @param length the telegraph length
*/
void setTelegraphLength(float length);
/**
* Get the telegraph width (used by LINE shape).
* @return the telegraph width
*/
float getTelegraphWidth();
/**
* Set the telegraph width.
* @param width the telegraph width
*/
void setTelegraphWidth(float width);
/**
* Get the telegraph angle in degrees (used by CONE shape).
* @return the telegraph angle in degrees
*/
float getTelegraphAngle();
/**
* Set the telegraph angle in degrees.
* @param angle the angle in degrees
*/
void setTelegraphAngle(float angle);
}
@@ -8,54 +8,78 @@ public interface IDataAbilities {
/**
* Check if the ability system is enabled for this NPC.
*
* @return true if enabled
*/
boolean isEnabled();
/**
* Enable or disable the ability system for this NPC.
*
* @param enabled whether to enable
*/
void setEnabled(boolean enabled);
/**
* Get all abilities assigned to this NPC (resolved from slots).
* Returns safe deep copies. Use {@link #getSourceAbility(String)} for live references.
*
* @return array of abilities
*/
IAbility[] getAbilities();
/**
* Add an inline ability to this NPC.
*
* @param ability the ability to add
*/
void addAbility(IAbility ability);
/**
* Add a reference ability by key (built-in name or custom UUID).
*
* @param key the ability reference key
*/
void addAbilityReference(String key);
/**
* Remove an ability by ID.
*
* @param abilityId the ability ID to remove
*/
void removeAbility(String abilityId);
/**
* Get an ability by ID.
* Returns a safe deep copy. Use {@link #getSourceAbility(String)} for the live reference.
*
* @param abilityId the ability ID
* @return the ability, or null
*/
IAbility getAbility(String abilityId);
/**
* Check if the NPC has an ability with the given ID.
*
* @param abilityId the ability ID
* @return true if found
*/
boolean hasAbility(String abilityId);
/**
* Check if a slot is a reference (by ability ID).
*
* @param abilityId the ability ID
* @return true if reference
*/
boolean isAbilityReference(String abilityId);
/**
* Convert a reference slot to inline (by ability ID).
* Returns false if the reference cannot be resolved.
*
* @param abilityId the ability ID
* @return true if converted successfully
*/
boolean convertToInline(String abilityId);
@@ -67,11 +91,15 @@ public interface IDataAbilities {
/**
* Get the currently executing ability, or null if none.
* Returns a safe deep copy. Use {@link #getSourceCurrentAbility()} for the live reference.
*
* @return the current ability, or null
*/
IAbility getCurrentAbility();
/**
* Check if any ability is currently executing.
*
* @return true if executing
*/
boolean isExecutingAbility();
@@ -87,11 +115,15 @@ public interface IDataAbilities {
/**
* Get the global cooldown timer in ticks.
*
* @return cooldown in ticks
*/
int getGlobalCooldown();
/**
* Set the global cooldown timer in ticks.
*
* @param ticks cooldown in ticks
*/
void setGlobalCooldown(int ticks);
@@ -10,6 +10,8 @@ public interface IPlayerAbilityData {
/**
* Get all unlocked ability keys.
*
* @return array of ability keys
*/
String[] getUnlockedAbilities();
@@ -22,26 +24,37 @@ public interface IPlayerAbilityData {
/**
* Lock (remove) an ability from this player.
*
* @param key the ability key
*/
void lockAbility(String key);
/**
* Check if the player has unlocked a specific ability.
*
* @param key the ability key
* @return true if unlocked
*/
boolean hasUnlockedAbility(String key);
/**
* Get the currently selected ability index.
*
* @return the selected index
*/
int getSelectedIndex();
/**
* Set the selected ability index.
*
* @param index the ability index
*/
void setSelectedIndex(int index);
/**
* Get the key of the currently selected ability.
*
* @return the selected ability key
*/
String getSelectedAbilityKey();
@@ -57,11 +70,15 @@ public interface IPlayerAbilityData {
/**
* Check if the player is currently executing an ability.
*
* @return true if executing
*/
boolean isExecutingAbility();
/**
* Get the currently executing ability.
*
* @return the current ability, or null
*/
IAbility getCurrentAbility();
@@ -77,6 +94,8 @@ public interface IPlayerAbilityData {
/**
* Check if the player is on universal cooldown.
*
* @return true if on cooldown
*/
boolean isOnCooldown();
@@ -107,11 +126,16 @@ public interface IPlayerAbilityData {
/**
* Activate the currently selected ability.
*
* @return true if activated
*/
boolean activateAbility();
/**
* Activate a specific ability by key.
*
* @param key the ability key
* @return true if activated
*/
boolean activateAbility(String key);
@@ -119,24 +143,33 @@ public interface IPlayerAbilityData {
/**
* Cycle a toggle ability to its next state.
* Off -> State 1 -> State 2 -> ... -> State N -> Off
* Off -> State 1 -> State 2 -> ... -> State N -> Off
* @param key the ability key
* @return The new state (0 = off, 1+ = active state number)
*/
int toggleAbility(String key);
/**
* Get the current toggle state for an ability.
*
* @param key the ability key
* @return 0 if not active, 1+ for active state
*/
int getToggleState(String key);
/**
* Set a toggle to a specific state. 0 = deactivate, 1+ = specific state.
*
* @param key the ability key
* @param state the toggle state
*/
void setToggleState(String key, int state);
/**
* Check if a toggle ability is currently active (any state > 0).
* Check if a toggle ability is currently active (any state > 0).
*
* @param key the ability key
* @return true if toggled on
*/
boolean isAbilityToggled(String key);
}
@@ -5,10 +5,13 @@ package noppes.npcs.api.ability.data;
* Controls where the projectile spawns relative to the caster.
*/
public interface IEnergyAnchorData {
/** @return Anchor point ordinal (0=FEET, 1=CENTER, 2=RIGHT_HAND, 3=LEFT_HAND, 4=HEAD, 5=FRONT, 6=ABOVE_HEAD). */
/** @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=FEET, 1=CENTER, 2=RIGHT_HAND, 3=LEFT_HAND, 4=HEAD, 5=FRONT, 6=ABOVE_HEAD). */
/**
* 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). */