Custom mechanics and API

Expose authorized mechanics

A server can deliberately permit movement that differs from vanilla. ArionAC must receive that authorization through real server capabilities, attributes or an explicit integration. A client cheat switch cannot grant permission.

• Creative/Spectator: these game modes have legitimate movement rules.
• Survival/Adventure flight: the flight plugin should set Player.setAllowFlight(true) and, when appropriate, setFlying(true).
• Speed boosts: use the supported server movement attributes or abilities, not an unexplained client-side speed.
• Custom double jumps, jump pads and launches: grant a short movement allowance before applying the custom mechanic.

Extreme attributes outside the bounded prediction model cause the affected movement decisions to stand down; this is not a promise to simulate an arbitrary 500× speed precisely. Purpur options with unmodeled semantics require explicit authorization rather than guessed vanilla behavior.

Custom movement API

Depend on the plugin named ArionAC and compile against de.venta.arionac.api.ArionACApi. Integrations built against the old SquidLab package must be updated and recompiled.

import de.venta.arionac.api.ArionACApi;

// Run on this player's owning server context, before your launch.
ArionACApi.allowCustomMovement(player, 2500, "BedWars fireball launch");
// Apply your authorized movement here.

// End the allowance early when the mechanic finishes.
ArionACApi.revokeCustomMovement(player);

Allowances accept 1–60,000 milliseconds. A repeated grant renews the bounded window. Movement/velocity evidence and corresponding physics divergence are suppressed during the authorized mechanic; combat, packet and interaction checks are not blanket-exempted.

Persistent custom movement modes

server-integration:
  custom-movement-worlds:
    - "custom-minigame-world"

Use trusted world names for worlds with intentionally different movement physics. Alternatively assign arionac.custom-movement only to trusted, server-managed mode players. This permission defaults to false, including operators. Do not give it to every normal player.

The broader ArionACApi.exempt(player, durationMs) and unexempt(player) methods affect all checks. They are usually too broad for an ordinary launch; prefer the movement-only allowance.

Thread and lifecycle contract

All player-related API methods must run on the player’s current owning context. On classic Spigot/Paper/Purpur this is the server main thread. In a Folia validation integration it is the player’s Entity Scheduler, which follows the entity across region/world changes.

Do not access the player API from Netty, an HTTP worker, an arbitrary async worker, a foreign region or the Folia Global Scheduler. Such calls return neutral results or make no change. A fixed location scheduler is not interchangeable with the entity’s current owner. Avoid blocking waits between regions.

Global check registration and enable operations belong to the global context. ArionACApi.setCheckEnabled changes runtime state only; unlike the dashboard or administrative toggle command, it does not save your configuration.

Other public API methods

Geyser and Floodgate

geyser:
  EXEMPT-BEDROCK-PLAYERS: true
  EXEMPT-CATEGORIES: []
  FLOODGATE-PREFIX: "."

Keep the exemption enabled unless you have a separate validated approach for Bedrock movement and interaction. An empty category list means all categories. The name prefix must match Floodgate configuration where prefix detection is needed; names alone are not a complete identity guarantee.