Mirage

A server-side Fabric library that provides a type-safe, fluent API for Minecraft's Display Entity system. It abstracts entity construction, spatial transformation, interpolation, and hierarchical grouping into a single cohesive toolkit for mod developers.

Overview

Mirage eliminates the repetitive boilerplate required to spawn and manipulate BlockDisplayEntity, ItemDisplayEntity, and TextDisplayEntity at runtime. Instead of manually composing NBT, sending packets, or tracking entity IDs, developers describe the desired state through a chainable builder API. The library handles entity lifecycle, transform matrices, and server-tick scheduling internally.

Capabilities

Display Construction

MirageBuilder supports all three vanilla display types through a unified interface. Configure position, affine transformation, interpolation duration, view range, shadow parameters, billboard mode, brightness override, and glow color before spawning.

Transform Hierarchies

MirageHierarchy and TransformNode implement a directed tree of local-to-world transforms. Each node caches its world matrix and invalidates lazily when ancestors change. The system supports arbitrary nesting, full pivot-point rotation, and scale inheritance.

Keyframe Animation

MirageAnimation sequences vanilla interpolation fields server-side. Define hold durations, transition durations, loop modes, ping-pong playback, and speed multipliers. The animator advances only after the current interpolation window completes, preventing state tearing.

Spatial Groups

MirageGroup maintains relative offsets from a shared center point. It supports bulk translation, rotation, and interpolated movement, as well as automatic distribution algorithms for linear, circular, and grid layouts.

Task Scheduling

MirageScheduler registers one-shot, repeating, and self-cancelling callbacks synchronized to the server tick. All task handles expose their next-run tick and period for inspection.

Quick Example

ServerWorld world = ...;

MirageDisplay hologram = MirageBuilder.in(world)
    .block(Blocks.DIAMOND_BLOCK.getDefaultState())
    .at(100.5, 64.0, 200.5)
    .transform(MirageTransform.identity().scale(2.0f))
    .glowColor(0xFF00FFFF)
    .buildAndSpawn();

hologram.lookAt(new Vec3d(110.0, 65.0, 210.0));

Mirage.animate(hologram)
    .keyframe(20, MirageTransform.identity().scale(2.0f))
    .keyframe(20, MirageTransform.identity().scale(2.5f))
    .loop(true)
    .pingPong(true)
    .play();

Requirements

• Minecraft 1.20.x or newer
• Fabric Loader and Fabric API
• JOML (bundled with Minecraft; no additional dependency)

Architecture

• Server-authoritative. All mutations originate on the server thread. The client receives standard display entity packets; no client-side installation is required for core functionality.
• Zero-allocation hot paths. MirageMath, MirageEasing, and TransformNode minimize heap pressure. World-matrix queries are constant-time after the initial cached computation.
• Pivot semantics. Pivot points are fully evaluated within the hierarchy pipeline via MirageTransform.toMatrix4d(). When applied directly to a vanilla AffineTransformation through build(), the pivot is omitted because the vanilla format does not store it.

Roadmap

Phase	Status	Deliverable
I	Released	Fabric 1.20.x core, builder API, display management
II	Released	Transform hierarchies, keyframe animation, spatial groups, tick scheduler
III	Planned	NeoForge 1.21.1+ port and cross-loader artifact publishing