# API Reference Painting-API provides the public interfaces for inspecting the pack registry and listening for pack lifecycle events. The API is platform-neutral — both `Painting-Paper` and `Painting-Velocity` register the same `IPaintingAPI` instance under `PaintingAPI.get()`. --- ## PaintingAPI The static entry point for all API access. ```java import gg.lode.paintingapi.PaintingAPI; if (PaintingAPI.isAvailable()) { IPaintingAPI api = PaintingAPI.get(); } ``` | Method | Description | |---|---| | `get()` | Returns the registered `IPaintingAPI`. Throws `IllegalStateException` if Painting hasn't initialized. | | `isAvailable()` | `true` if the API has been registered. | | `setApi(IPaintingAPI)` | Internal — called by platform plugins on enable. Throws if already set. | --- ## IPaintingAPI The platform-neutral facade. Implemented by `PackManager` on both Paper and Velocity. ```java IPaintingAPI api = PaintingAPI.get(); ``` | Method | Description | |---|---| | `isEnabled()` | `true` if Painting is enabled in config. | | `getPackDefinitions()` | A snapshot list of every configured `PackDefinition`. | | `getPackDefinition(String)` | A single pack by name, or `null` if not configured. | | `getServerEntries()` | A snapshot list of every configured `ServerEntry`. | | `isRequiredForServer(String)` | `true` if any server entry matching the name has `required: true`. | | `reload()` | Reload pack and server registries from disk. | | `resendPacksToOnlinePlayers()` | Resend pack offers to every online player. | | `resendPacksToPlayer(UUID)` | Resend pack offers to a specific player. | --- ## Model Classes ### PackDefinition A named pack with one or more variants. | Method | Description | |---|---| | `name()` | The pack name from config. | | `variants()` | Unmodifiable list of `PackVariant` in declaration order. | | `pickFor(int protocol)` | Returns the first variant whose protocol set contains the given protocol, or `null`. (Note: this convenience method does **not** evaluate version expressions — use `PackManager.pickVariant` internally for full resolution.) | ### PackVariant A single URL/hash pair gated by protocols and/or version expressions. | Method | Description | |---|---| | `url()` | Pack download URL. | | `hash()` | SHA-1 hash, hex-encoded. May be empty if not yet generated. | | `protocols()` | Unmodifiable set of protocol numbers this variant matches. | | `versionExpressions()` | Unmodifiable list of version expressions (e.g. `1.21+`, `>=1.21.4,<26.1`). | | `matches(int protocol)` | `true` if the protocol is in the variant's protocol set. | ### ServerEntry A regex-keyed group of packs to send. | Method | Description | |---|---| | `name()` | Entry name from config. | | `pattern()` | Compiled `Pattern` of the regex. | | `required()` | `true` if declining or failing should kick the player. | | `packs()` | Unmodifiable list of pack names to send, in order. | | `matches(String serverName)` | `true` if the server name matches `pattern()`. | ### PackStatus Enum representing the player's resource pack state. | Value | Meaning | |---|---| | `ACCEPTED` | Prompt accepted. | | `DOWNLOADED` | Download finished. | | `LOADED` | Pack applied. | | `DECLINED` | Prompt declined. | | `FAILED` | Download failed. | | `DISCARDED` | Pack unloaded. | | `INVALID_URL` | Client rejected the URL. | | `UNKNOWN` | Future status not mapped. | --- ## Version Expressions ### VersionExpression Parsed form of a single comparison like `>=1.21.4` or `1.21+`. | Method | Description | |---|---| | `parse(String)` | Static factory. Recognises `>=`, `<=`, `>`, `<`, trailing `+` (alias for `>=`), or bare version (`EQ`). | | `operator()` | The `Operator` enum (`EQ`, `GT`, `GTE`, `LT`, `LTE`). | | `version()` | The version string after stripping the operator. | | `evaluate(int playerProtocol, int referenceProtocol)` | Evaluate the comparison against two protocol numbers. | ### VersionResolver Maps version strings to protocol numbers and evaluates compound expressions. | Method | Description | |---|---| | `protocolFor(String)` | Looks up a version's protocol number, or `null` if unknown. | | `override(String, int)` | Inserts or updates a single mapping (used when reading `version_protocols:` from config). | | `overrideAll(Map)` | Bulk insert. | | `table()` | A defensive copy of the version-to-protocol map. | | `evaluateExpressions(Collection<String>, int playerProtocol)` | Evaluates a list of expressions (OR semantics across the list, AND across comma-separated terms within each entry). Throws `IllegalArgumentException` for unknown versions. | The bundled `version_protocols.yml` in the API jar covers 1.21 through 26.1.2 at the time of release. Override or extend in plugin config under `version_protocols:`. --- ## Event Interfaces The `gg.lode.paintingapi.api.event` package declares platform-neutral interfaces. Each platform plugin provides a concrete subclass that integrates with the host event bus. ### PackStatusEvent | Method | Description | |---|---| | `getPlayerId()` | Player UUID. | | `getServerName()` | Server name the status is reported against. | | `getStatus()` | A `PackStatus` value. | | `isRequiredForServer()` | `true` if the matching server entry is `required: true`. | Concrete implementations: `PaperPackStatusEvent` (Bukkit event), `VelocityPackStatusEvent` (Velocity event). ### PackPreSendEvent | Method | Description | |---|---| | `getPlayerId()` | Player UUID. | | `getServerName()` | Server name being sent. `<proxied>` when delivered through the proxy push path on Paper. | | `getPackName()` | Pack name from config. | | `getPackUrl()` | Pack URL (post hash-append if enabled). | | `getPackHash()` | SHA-1 hash. | | `isCancelled()` / `setCancelled(boolean)` | Cancel the offer for this pack. | Concrete implementations: `PaperPackPreSendEvent` (cancellable Bukkit event), `VelocityPackPreSendEvent` (interface-only — Velocity's native dispatch is currently used by Paper-side pre-send only). ### PackRegistryReloadEvent | Method | Description | |---|---| | `getDefinitionCount()` | Number of pack definitions after reload. | | `getServerEntryCount()` | Number of server entries after reload. | Concrete implementation: `PaperPackRegistryReloadEvent` (Bukkit event fired after `/painting reload`). --- ## Related Pages - [[Painting/Developers/Overview]] — getting started and usage examples - [[Painting/API/PaintingAPI]] — static accessor source - [[Painting/API/IPaintingAPI]] — platform-neutral interface source - [[Painting/Server Owners/Commands]] — `/painting reload` triggers `PackRegistryReloadEvent`