Mirage

A server-side Fabric library that provides a type-safe, fluent API for Minecraft's Display Entity system, plus a small VFX layer (particle shapes, positional sound, eased tweens, motion splines) built on top of it. 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, easing, and server-tick scheduling internally.

Capabilities

Display Construction

MirageBuilder / MirageDisplay support 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 — plus lookAt()/faceTowards() for instant orientation toward a point.

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, off-center pivot rotation, and scale inheritance.

Keyframe Animation

MirageAnimation sequences vanilla interpolation fields server-side — cheap, and ideal for looping or long-running motion, since the client handles the tween itself. Define hold durations, transition durations, loop modes, ping-pong playback, and speed multipliers.

Eased Tweens

MirageTween drives a display from one transform to another over a fixed duration, re-evaluating a MirageEasing curve (easeOutBack, easeInOutCubic, etc.) every server tick, so non-linear motion — including overshoot — actually shows up client-side. Vanilla interpolation is linear-only, so this is the piece that makes MirageEasing (previously decorative) do something. Costs one packet per tick for the tween's duration, so it's meant for short, expressive one-shots — a UI pop-in, a hit reaction, a snap-to-target — not for permanent looping motion (use MirageAnimation for that).

Particle VFX

mrkieha.mirage.fx.MirageParticle builds actual particle geometry out of vanilla's single-point spawnParticles call: lines, circles (including a rotating-phase overload for spinning rings), Fibonacci-lattice spheres, helices, and box outlines.

Positional Sound

mrkieha.mirage.fx.MirageSound wraps ServerWorld#playSound for effects tied to a world point rather than an entity, with a playVaried helper that jitters pitch so repeated hits/impacts don't sound robotic.

Motion Splines

MirageSpline builds a centripetal Catmull-Rom curve through a list of waypoints (open or looping) and evaluates or samples smooth positions along it — for orbit paths, projectile trails, or camera-style holograms.

Color Utilities

MirageColor packs/unpacks ARGB, lerps between colors, and converts HSV — including a one-line rainbow(tick, period) helper for cycling glow or particle colors.

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(MirageColor.rgb(0, 255, 255))
    .buildAndSpawn();

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

// Loop a gentle pulse forever (vanilla client interpolation):
Mirage.animate(hologram)
    .keyframe(20, MirageTransform.identity().scale(2.0f))
    .keyframe(20, MirageTransform.identity().scale(2.5f))
    .loop(true)
    .pingPong(true)
    .play();

// One-shot pop-in with overshoot, driven server-side:
Mirage.tween(hologram,
        MirageTransform.identity().scale(0f),
        MirageTransform.identity().scale(2.0f),
        12, MirageEasing::easeOutBack)
    .start()
    .playOn(Mirage.schedule());

// Ring of particles that spins by advancing the phase each tick:
Mirage.schedule().runRepeating(0, 1, () ->
    MirageParticle.circle(world, ParticleTypes.END_ROD, hologram.getPos(), 1.5, 16, (float) (world.getTime() * 0.1))
);

Requirements

• Minecraft 1.20.1
• 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 / particle / sound 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 baked in both MirageTransform.toMatrix4d() (used by the TransformNode hierarchy) and MirageTransform.build() (the vanilla AffineTransformation path) — rotating or scaling around an off-center pivot works whether you go through a hierarchy or spawn a display directly.

Roadmap