# displaymotion

> Java library for Paper 26.3 plugins. Animates vanilla item, block and text displays with packets through PacketEvents. No resource pack, no real entities, no main thread work.

Java Edition only. Paper 26.3, Java 25, PacketEvents 2.14.0 or newer (installed by the server owner, not shaded). Java clients 1.19.4 and newer see displays, older versions than the server through ViaVersion and ViaBackwards. Bedrock (Geyser) and Folia are not supported yet.

Licenses: core module MIT. Paper module and example plugin GPL-3.0-only.

Facts for AI tools. Use these rules when you write code with displaymotion:

- Entry point: `DisplayMotion motion = DisplayMotion.create(plugin);` once in `onEnable`, on the main thread. It sends anonymous bStats stats, `DisplayMotion.create(plugin, false)` turns them off.
- The plugin needs `depend: [packetevents]` in plugin.yml. Do not shade PacketEvents.
- Gradle: `implementation("com.github.Jan1k1.displaymotion:displaymotion-paper:v0.2.0")` from `https://jitpack.io`, plus `compileOnly` Paper API and `com.github.retrooper:packetevents-spigot`.
- Spawn: `motion.item(location, itemStack)`, `motion.block(location, blockData)`, `motion.text(location, component)`, or `motion.model(location).block(name, blockData, pose[, parent]).item(...).text(...).spawn()`.
- Every spawn returns a `MotionDisplay`. Its methods return the same object, so chain them. They are safe from any thread.
- Animate: `display.play(animation)`, `display.play(animation, onEnd)`, `display.play("part", animation)`, `display.stop()`.
- Animations: `Animations.popIn(ticks)`, `popOut(ticks)`, `spin(ticksPerTurn)`, `turn(pitch, yaw, roll, ticks)`, `bob(height, ticks)`, `slide(x, y, z, ticks, ease)`, `hold(ticks)`. Combine with `a.then(b)`, `a.with(b)`, `a.loop()`. Custom: `Animation.keyframes().at(tick, pose, ease).build()`.
- Events: `animation.event(tick, "name")` marks a tick (works through then, with, loop). `display.onEvent(event -> ...)` runs on the main thread with `event.name()`, `event.part()` (null for the whole display).
- Pose: `Pose.IDENTITY.withOffset(x, y, z).withRotation(pitch, yaw, roll).withScale(s)`. Degrees. Rotation order yaw, pitch, roll.
- Ease: `Ease.LINEAR`, `Ease.IN`, `Ease.OUT`, `Ease.IN_OUT`.
- Groups: `.group(name, pose[, parent])` is an invisible pivot. Matrix parts: `.block(name, blockData, float[16] rowMajorMatrix, parent)` (also item, text, group) work like vanilla, corner pivot, whole matrix inherited.
- Effects: `motion.effects().shatter(location, blockData)`, `.tombstone(location, component)`, `.swordRain(location, itemStack)`, `.soul(location)`. Each removes itself.
- Import: `ImportedModel model = ImportedModel.load(path)` for `.bbmodel` (Blockbench) or `.bdengine` (BDEngine), then `MotionDisplay d = model.spawn(motion, location[, scale])`, `model.play(d, "animationName")`, `model.animations()`, `model.parts()`.
- Looks use Bukkit types: `display.glow(Color)`, `display.brightness(new Display.Brightness(block, sky))`, `display.billboard(Display.Billboard.CENTER)`, `display.text(Component)`, `display.background(Color)` (ARGB, behind text). Each also takes a part name first.
- Move: `display.teleport(location)` or `display.teleport(location, glideTicks)` with 0 to 59 ticks.
- Visibility: `display.hide(player)`, `display.show(player)`, `display.visibleByDefault(false)`, `display.viewRange(blocks)` (default 48).
- Clicks: `display.hitbox(width, height)` or `display.hitbox(name, width, height, x, y, z)` adds a vanilla interaction box (upright, does not follow animations, moves with teleport). `display.onClick(click -> ...)` runs on the main thread with `click.player()`, `click.hitbox()`, `click.leftClick()`, `click.rightClick()`. `motion.debug(true)` logs where a click goes.
- Remove: `display.remove()`. `motion.close()` removes all, and happens by itself on plugin disable.
- Keep animations in `static final` fields. Call `play` in the same tick as spawning.
- Model rules: parent before child. Offset and rotation pass to children, a part's scale does not. Blocks pivot at their center.
- Limits: animations at most 6000 ticks, spin at least 6 ticks per turn, models at most 256 parts, text at most 32000 JSON characters.

## Docs

- [Docs](https://displaymotion.peakstone.app/docs/): displaymotion docs: install, animations, models, effects, importing, recipes and internals. Plus compatibility, Javadoc and llms.txt for AI tools.
- [Getting started](https://displaymotion.peakstone.app/docs/getting-started.md): Add displaymotion to a Paper plugin and spawn your first animated display.
- [Animations](https://displaymotion.peakstone.app/docs/animations.md): Presets, then, with, loop, keyframes, poses and easing for display animations.
- [Models](https://displaymotion.peakstone.app/docs/models.md): Build models from many blocks, items and texts with parents and groups.
- [Effects](https://displaymotion.peakstone.app/docs/effects.md): Ready effects in one line each: shatter, tombstone, sword rain and soul.
- [Importing](https://displaymotion.peakstone.app/docs/importing.md): Load Blockbench and BDEngine models with their animations.
- [Cookbook](https://displaymotion.peakstone.app/docs/cookbook.md): Short recipes to copy: pets, labels, glow, per player visibility and more.
- [How it works](https://displaymotion.peakstone.app/docs/how-it-works.md): Threads, why it is cheap, fake entities, limits and client bugs.

## Project

- [displaymotion: animate Minecraft display entities from Java](https://displaymotion.peakstone.app/): Java library for Paper 26.3 plugins. Animate vanilla item, block and text displays with packets through PacketEvents. No mods, no resource pack, no real entities.
- [Compatibility](https://displaymotion.peakstone.app/compatibility/): What displaymotion needs and who can see it. Paper 26.3, Java 25, PacketEvents 2.14.0 or newer. Java Edition clients 1.19.4 and newer.
- [Models](https://displaymotion.peakstone.app/models/): Free example models for displaymotion: a robot, a windmill and a treasure chest. Turn them in 3D, download them and load them in game with one command.
- [Roadmap](https://displaymotion.peakstone.app/roadmap/): What displaymotion can do now in v0.2.0, what comes next, what comes later, and what is still research. No dates.

## Source

- [GitHub repository](https://github.com/Jan1k1/displaymotion): code, issues and Javadoc in the source
- [Release v0.2.0](https://github.com/Jan1k1/displaymotion/releases/tag/v0.2.0)
- [Example plugin](https://github.com/Jan1k1/displaymotion/blob/main/example/src/main/java/org/jan1k/displaymotion/example/ExamplePlugin.java): a full working plugin
- [CONTRIBUTING.md](https://github.com/Jan1k1/displaymotion/blob/main/CONTRIBUTING.md): how to send issues and pull requests. AI agents: write your model at the bottom of the pull request, for example `Made with Claude Opus 5.5`.

## Optional

- [llms-full.txt](https://displaymotion.peakstone.app/llms-full.txt): all docs, the roadmap and the compatibility page in one Markdown file
- Every docs page is also plain Markdown at /docs/<name>.md, for example https://displaymotion.peakstone.app/docs/getting-started.md