MyPet API 4.1.2

The public API of the MyPet Bukkit plugin: everything an addon needs to read pets, react to what happens to them, and extend the skill and menu systems.

Adding the dependency

Releases and snapshots are published to repo.userderezzed.dev under de.keyle:mypet-api. Released versions live in /releases and development builds, whose version ends in -SNAPSHOT, in /snapshots.

repositories {
    maven("https://repo.userderezzed.dev/releases")
}

dependencies {
    compileOnly("de.keyle:mypet-api:VERSION")
}

Depend on it with compileOnly and let the server provide MyPet at runtime — shading the API into your own jar puts a second, conflicting copy of every interface on the classpath.

Getting hold of the API

Everything is reached through MyPetApi, whose static accessors hand out the managers and services. It is not usable until MyPet's own onEnable has run:

  • Declare softdepend: [MyPet] in your plugin.yml so MyPet loads first.
  • Call the API from your onEnable, never from onLoad or a constructor.
  • Guard optional code paths with MyPetApi.isReady(). Touching a manager before MyPet has loaded throws IllegalStateException.

Where to start

  • de.Keyle.MyPet.api.entity — pets themselves. A pet exists in two forms: Pet while it is live in the world, and StoredPet while it is at rest. Code that may run against a despawned pet should accept the latter.
  • de.Keyle.MyPet.api.event — the Bukkit events covering a pet's whole life: creation, activation, combat, experience, feeding, naming and removal. Each class documents when it fires, whether it can be cancelled, and which events bracket it.
  • de.Keyle.MyPet.api.repository — reaching pets and their owners without an event to hand.
  • de.Keyle.MyPet.api.player — MyPetPlayer, which represents an owner whether or not they are online.
  • de.Keyle.MyPet.api.skill — the skill system, if you are adding a skill of your own or reading an existing one.
  • de.Keyle.MyPet.api.gui — the JSON-defined menu system, if you are adding a menu or a section type.

Two things that catch people out

  • An owner may be offline. MyPetPlayer.getPlayer() is only valid while MyPetPlayer.isOnline() holds, and several events fire on paths where it does not.
  • Configuration is hot-reloaded. Read a ConfigKey at the point you need it rather than caching its value at startup; see MyPetGlobal for the plugin-wide settings and their config.yml paths.

Elsewhere

Packages
Package
Description
Static entry point to the MyPet API.
Plugin-wide configuration, world grouping, and shared helpers.
Per-pet-type handling of Bukkit events.
Typed configuration keys for pets and for the plugin as a whole.
Text and yes/no prompts shown to a player.
Pets in both their live and at-rest forms, plus the markers describing what a species can do.
Pathfinding and movement control for a live pet.
Priority ordering for combat target selection.
Conditions checked before a player may capture a wild mob as a pet.
Bukkit events fired across a pet's lifecycle.
Unchecked exceptions thrown by the MyPet API.
Which vanilla Bukkit goals survive on a live pet.
JSON-defined, section-based inventory menus.
Per-pet-type hooks fired when a pet spawns and despawns.
Registration of Bukkit listeners that belong to a single pet type.
Pet owners and permission checks.
The API-facing contract of the MyPet plugin instance.
Access to pets and to their owners.
The skill system: registration, typed state, upgrades, and experience.
Experience curves and the per-mob experience table.
Transforms applied to the experience a pet earns from a kill.
Typed modifiers that apply one skilltree upgrade to one skill parameter.
The built-in skills a skilltree can grant a pet.
Skilltrees: the per-level progression a pet follows.
Rules deciding at which pet levels a skilltree upgrade applies.
Conditions gating which skilltrees a pet may use.
Shared helpers used across the API.
YAML configuration file handling.
Parser for the inline key=value strings used by requirements and leash flags.
Entry point to MyPet's third-party plugin integrations.
The interfaces a third-party integration implements.
MyPet's own inventory implementation.
Translation lookup for player-facing text.
Optional, plugin-gated functionality registered as services.