Changes

Page history
feat: a lot of missing stuff part 2 authored by Taiyou06's avatar Taiyou06
Show whitespace changes
Inline Side-by-side
API.md
View page @ d71b3f35
......@@ -39,7 +39,7 @@ repositories {
<dependency>
<groupId>io.lumine</groupId>
<artifactId>Mythic-Dist</artifactId>
<version>5.6.1</version>
<version>5.12.1</version>
<scope>provided</scope>
</dependency>
```
......@@ -47,14 +47,14 @@ repositories {
```groovy
dependencies {
//...
compileOnly 'io.lumine:Mythic-Dist:5.6.1'
compileOnly 'io.lumine:Mythic-Dist:5.12.1'
}
```
#### Gradle (Kotlin)
```kotlin
dependencies {
// ...
compileOnly("io.lumine:Mythic-Dist:5.6.1")
compileOnly("io.lumine:Mythic-Dist:5.12.1")
}
```
--------------------------
......@@ -109,20 +109,197 @@ optActiveMob.ifPresent(activeMob -> {
```java
Collection<ActiveMob> activeMobs = MythicBukkit.inst().getMobManager().getActiveMobs(am -> am.getMobType().equals("SkeletalKnight"));
```
<!--
Registering Custom Components
-----------------------------
Addons can register their own mechanics, conditions, targeters, and placeholders using the same annotation-based system Mythic uses internally, plus custom triggers. Add MythicMobs to `depend` (or `softdepend`) in your `plugin.yml` first.
### Custom Mechanics
A mechanic is a class annotated with `@MythicMechanic`, extending `SkillMechanic`, and implementing one of the dispatch interfaces:
- `INoTargetSkill` — `SkillResult cast(SkillMetadata data)`
- `ITargetedEntitySkill` — `SkillResult castAtEntity(SkillMetadata data, AbstractEntity target)`
- `ITargetedLocationSkill` — `SkillResult castAtLocation(SkillMetadata data, AbstractLocation target)`
The constructor must match the superclass signature `(SkillExecutor, File, String, MythicLineConfig)`. Read your attributes from the `MythicLineConfig`.
```java
package com.example.myplugin.mythic.mechanics;
import io.lumine.mythic.api.adapters.AbstractEntity;
import io.lumine.mythic.api.config.MythicLineConfig;
import io.lumine.mythic.api.skills.ITargetedEntitySkill;
import io.lumine.mythic.api.skills.SkillMetadata;
import io.lumine.mythic.api.skills.SkillResult;
import io.lumine.mythic.core.skills.SkillExecutor;
import io.lumine.mythic.core.skills.SkillMechanic;
import io.lumine.mythic.core.utils.annotations.MythicMechanic;
import org.bukkit.entity.Player;
import java.io.File;
@MythicMechanic(author = "You", name = "greet", aliases = {"hello"},
description = "Sends a message to the target player")
public class GreetMechanic extends SkillMechanic implements ITargetedEntitySkill {
private final String message;
public GreetMechanic(SkillExecutor manager, File file, String line, MythicLineConfig mlc) {
super(manager, file, line, mlc);
this.message = mlc.getString(new String[]{"message", "msg", "m"}, "Hello!");
}
@Override
public SkillResult castAtEntity(SkillMetadata data, AbstractEntity target) {
if (target.isPlayer()) {
((Player) target.getBukkitEntity()).sendMessage(message);
}
return SkillResult.SUCCESS;
}
}
```
Used in config as `- greet{message=Hi!} @target`.
### Custom Conditions & Targeters
Conditions and targeters follow the same pattern. Annotate the class and extend the matching base type:
- **Conditions** — `@MythicCondition`, extend `SkillCondition` and implement `IEntityCondition`, `ILocationCondition`, or `ISkillMetaCondition`.
- **Targeters** — `@MythicTargeter`, extend `IEntitySelector` (entity targeters) or `ILocationSelector` (location targeters).
Both are picked up by the same package scan shown below.
### Registering Mechanics, Conditions & Targeters
Create a `CustomComponentRegistry` pointing at the package(s) holding your annotated classes. The constructor automatically scans for mechanics, conditions, targeters, and drops:
```java
// in your plugin's onEnable(), after MythicMobs is enabled
new CustomComponentRegistry(this, "com.example.myplugin.mythic");
```
You can also register a specific component type from a specific package:
```java
new CustomComponentRegistry(this, "com.example.myplugin.mythic")
.registerCustomComponent(CustomComponentRegistry.MythicComponentType.MECHANIC,
"com.example.myplugin.mythic.mechanics");
```
### Custom Placeholders
Placeholders use the `@MythicPlaceholder` annotation and are registered with the `PLACEHOLDER` component type. They are **not** picked up by the base package scan, so register them explicitly:
```java
new CustomComponentRegistry(this, "com.example.myplugin.mythic")
.registerCustomComponent(CustomComponentRegistry.MythicComponentType.PLACEHOLDER,
"com.example.myplugin.mythic.placeholders");
```
See the full [Placeholders API](/API/Placeholders) page for how to write a placeholder class, fetch arguments, and use the scoped and wildcard variants.
### Custom Triggers
A trigger is a `SkillTrigger` created with a name and optional aliases, then registered:
```java
import io.lumine.mythic.api.skills.SkillTrigger;
public final class MyTriggers {
public static final SkillTrigger CUSTOM_EVENT =
SkillTrigger.create("CUSTOMEVENT", "MYEVENT");
public static void register() {
SkillTrigger.register(CUSTOM_EVENT); // or: CUSTOM_EVENT.register();
}
}
```
Call `MyTriggers.register()` in your `onEnable()`. In mob configs the trigger is referenced by adding the `~on` prefix to the registered name — Mythic strips `~on` and matches the rest case-insensitively. So `CUSTOMEVENT` is used as `~onCustomEvent`, and the alias `MYEVENT` as `~onMyEvent`.
To make a mob's skills with that trigger actually fire, dispatch it through the event bus. The caster is the `SkillCaster` running the skill (an `ActiveMob` is a `SkillCaster`); `triggerEntity` is the entity that caused it, or `null`:
```java
ActiveMob mob = ...; // your MythicMob (implements SkillCaster)
AbstractEntity triggerEntity = ...; // the cause, may be null
MythicBukkit.inst().getSkillManager().getEventBus()
.processTrigger(MyTriggers.CUSTOM_EVENT, mob, triggerEntity, /* sync */ false);
```
Events
------
| | |
|------------------------------------------------------------------|------------------------------------------------|
| Event | Description |
| [MythicReloadedEvent](/api/events/MythicReloadedEvent) | Called when the plugin is reloaded |
| [MythicMobSpawnEvent](/api/events/MythicMobSpawnEvent) | Called when a MythicMob spawns |
| [MythicMobDeathEvent](/api/events/MythicMobDeathEvent) | Called when a MythicMob dies |
| [MythicMobDespawnEvent](/api/events/MythicMobDespawnEvent) | Called when a MythicMob despawns without dying |
| [MythicMobLootDropEvent](/api/events/MythicMobLootDropEvent) | Called right before a loot table is generated |
| [MythicConditionLoadEvent](/api/events/MythicConditionLoadEvent) | Called when a custom condition is loaded |
| [MythicDropLoadEvent](/api/events/MythicDropLoadEvent) | Called when a custom drop is loaded |
| [MythicMechanicLoadEvent](/api/events/MythicMechanicLoadEvent) | Called when a custom mechanic is loaded |
| [MythicTargeterLoadEvent](/api/events/MythicTargeterLoadEvent) | Called when a custom targeter is loaded |
-->
\ No newline at end of file
The Mythic API exposes the following Bukkit events. Full method signatures and fields are documented in the [JavaDocs](https://www.mythiccraft.io/javadocs/mythic/). A checkmark in the *Cancellable* column means the event implements `Cancellable`.
### Reload & Lifecycle
| Event | Description | Cancellable |
|-------|-------------|:-----------:|
| MythicPreReloadEvent | Fired at the start of the reload command before reload work begins. | |
| MythicReloadEvent | Fired after Mythic reloads configuration in reload stage one. | |
| MythicReloadedEvent | Fired after reload stage two completes and clocks are reloaded. | |
| MythicPostReloadedEvent | Fired after MythicReloadedEvent during reload stage two. | |
| MythicReloadCompleteEvent | Fired at the end of reload processing after completion messaging. | |
### Config Loading
| Event | Description | Cancellable |
|-------|-------------|:-----------:|
| MythicConditionLoadEvent | Requests a custom condition implementation for a config entry. | |
| MythicMechanicLoadEvent | Requests a custom mechanic implementation for a config entry. | |
| MythicTargeterLoadEvent | Requests a custom targeter implementation for a config entry. | |
| MythicDropLoadEvent | Requests a custom drop implementation for a config entry. | |
| MythicPlaceholdersLoadEvent | Event fired as MythicMobs registers placeholders, before it finalizes them | |
| MythicStatsRegistrationEvent | Fired after Mythic registers its built-in primary stats. | |
| MythicMenusPreLoadEvent | Fired immediately before Mythic loads custom menu configs. | |
### Mobs
| Event | Description | Cancellable |
|-------|-------------|:-----------:|
| MythicMobPreSpawnEvent | Fired before Mythic attempts to spawn a mob entity. | yes |
| MythicMobPreSpawnConfigureEvent | Called when a MythicMob is about to be spawned and currently in pre-spawn configuration stage | |
| MythicMobSpawnEvent | Fired after a Mythic mob entity is created and wrapped, but before registration. | yes |
| MythicMobDeathEvent | Fired for active Mythic mobs during Bukkit death handling. | |
| MythicMobDespawnEvent | Fired when an active Mythic mob despawns through Mythic's despawn handler. | |
| MythicMobInteractEvent | Fired when a player right-clicks an active Mythic mob. | |
| MythicMobEggEvent | Fired when a player uses a Mythic egg item. | yes |
| MythicMobLootDropEvent | Fired when Mythic has generated a loot bag for a mob death context. | |
| MythicMobItemGenerateEvent | Fired when a Mythic item definition has been materialized into a Bukkit stack. | |
### Combat & Skills
| Event | Description | Cancellable |
|-------|-------------|:-----------:|
| MythicDamageEvent | Fired when a Mythic damage mechanic prepares to apply damage to a target. | yes |
| MythicHealMechanicEvent | Fired when a Mythic healing mechanic is about to apply healing. | yes |
| MythicSkillEvent | Fired before a Mythic skill executes its mechanic queue. | yes |
| MythicTriggerEvent | Fired before Mythic executes trigger mechanics for a parent skill. | |
| MythicTargetEvent | Fired after a Mythic targeter is resolved but before the fallback is checked. | |
| MythicProjectileHitEvent | Fired when a Mythic projectile tracker intersects an entity target. | |
| MythicPlayerAttackEvent | Represents a player attack context in Mythic's Bukkit event layer. | |
### Auras, Stats & Items
| Event | Description | Cancellable |
|-------|-------------|:-----------:|
| MythicAuraStartEvent | Called when an Aura is about to be applied to an entity or location Cancelling this event will prevent the aura from being applied | yes |
| MythicAuraStopEvent | Called when an Aura is stopped/terminated | |
| MythicStatChangeEvent | Fired when a tracked stat value changes for a caster. | |
| MythicApplyEnchantEvent | Fired before Mythic applies one enchantment to an item. | |
| MythicModifiedInventoryEvent | Fired after Mythic mutates a Bukkit player's inventory. | |
### Cinematics
| Event | Description | Cancellable |
|-------|-------------|:-----------:|
| MythicCinematicStartEvent | Fired before a cinematic camera path begins playing for a player. | yes |
| MythicCinematicEndEvent | Fired when a cinematic camera path ends for a player (natural finish, manual cancel, player quit, or player death). | |
### Players & Variables
| Event | Description | Cancellable |
|-------|-------------|:-----------:|
| MythicPlayerLoadedEvent | Fired after a PlayerData profile is initialized for an online player. | |
| MythicPlayerQuitEvent | Fired when Mythic unloads a player's profile during quit handling. | |
| MythicPlayerSignalEvent | Fired when the signal mechanic targets a player profile. | |
| MythicPlayerVariableSetEvent | Fired before a player variable entry is written. | |
| MythicPlayerVariableRemoveEvent | Describes removal of a player variable entry. | |
### Packets (advanced)
| Event | Description | Cancellable |
|-------|-------------|:-----------:|
| MythicPacketItemDataEvent | Fired for outbound item stack packets intercepted by volatile packet handlers. | |
| PlayerActionPacketEvent | Fired for inbound player action packets intercepted by volatile packet handlers. | yes |