Mirage Kit

Mirage

A Fabric library for programmatic control of Minecraft's DisplayEntity system. Built for developers who need precise spatial manipulation, physics-backed interaction, dynamic lighting, and smooth interpolation without writing boilerplate NBT or packet code.

What It Does

Mirage abstracts the vanilla display entity pipeline into a type-safe, fluent API. You describe what you want — a scaled block, a rotated item, a facing text label — and the library handles entity construction, transformation matrices, interpolation timing, and hierarchy propagation.

The toolkit splits into four functional layers:

• Core — Server-side display spawning, transform hierarchies, keyframe animation, tick scheduling, and spatial grouping.
• Physics — Server-side Oriented Bounding Box math (SAT, sweep, raycast) with world block collision resolution.
• Lighting — Server-authoritative dynamic light sources (point, spot, ambient) synced to clients and injected into the vanilla lightmap.
• Client — Additive glow rendering, debug wireframes, and light volume visualization. Requires the mod on both sides for full feature set.

Target Audience

This is a developer library, not a player-facing mod. If you are building:

• Custom boss encounters with moving holographic constructs
• Procedural structures that need collision-aware placement
• Cutscene systems with interpolated camera-target displays
• Visual scripting tools that manipulate entities at runtime

...then Mirage eliminates the repetitive entity-management code.

Key Features

Display Abstraction

MirageBuilder and MirageDisplay wrap BlockDisplayEntity, ItemDisplayEntity, and TextDisplayEntity with a single fluent interface. No casting, no raw NBT, no manual packet sends.

Transform Hierarchy

TransformNode and MirageHierarchy let you parent displays to each other. Move the root and children follow automatically, with lazy world-matrix caching and dirty-flag invalidation.

Keyframe Animation

MirageAnimation drives vanilla interpolation fields server-side. Define hold times, transition durations, loop modes, ping-pong, and speed multipliers. Tick it from your scheduler — no client mods required for basic motion.

OBB Physics

Real oriented bounding boxes with arbitrary rotation. Full 15-axis SAT for intersection, penetration vector extraction, linear sweep CCD, and slab-method raycast. OBBWorld queries solid blocks and resolves collisions with configurable restitution, friction, and push-out behavior.

Dynamic Lighting

MirageLight sources are created on the server and synced to every client in the dimension. The client renderer rebuilds a block-light contribution cache every 5 ticks and injects it into LightingProvider.getLight, so vanilla shaders pick it up automatically.

Custom Glow

MirageGlowRenderer draws an additive billboarded quad over displays after vanilla render. ClientGlowManager stores per-entity pulse, scale, and intensity profiles locally.

Quick Example

ServerWorld world = ...;

// Spawn a diamond block, scaled 2x, facing the player
MirageDisplay hologram = MirageBuilder.in(world)
    .block(Blocks.DIAMOND_BLOCK.getDefaultState())
    .at(100.5, 64, 200.5)
    .transform(MirageTransform.identity().scale(2f))
    .glowColor(0xFF00FFFF)
    .buildAndSpawn();

// Make it look at a target
hologram.lookAt(new Vec3d(110, 65, 210));

// Animate scale pulse
new MirageAnimation(hologram)
    .keyframe(20, MirageTransform.identity().scale(2f))
    .keyframe(20, MirageTransform.identity().scale(2.5f))
    .loop(true)
    .pingPong(true)
    .play();

Technical Requirements

• Minecraft 1.20.x or newer
• Fabric Loader + Fabric API
• JOML (bundled with Minecraft, no extra dependency)

Architecture Notes

• Server-authoritative. All state changes originate on the server. The client only receives light packets and renders glow; it does not simulate physics or animation.
• Zero-allocation hot paths. MirageMath, MirageEasing, and OBBSAT avoid heap pressure where possible. TransformNode uses dirty-flag caching so world-matrix queries are O(1) after the first read.
• Iris-compatible. The client mixin injects glow at RETURN of DisplayEntityRenderer.render, after vanilla and Sodium/Iris have finished their work. No framebuffer hacks, no shader conflicts.

Roadmap

License

Copyright (c) 2026 MrKieha (Mirage Kit)

Permission is hereby granted to use, modify, and distribute this software and its derivatives, subject to the conditions below.

Attribution. Any mod or library that uses, includes, or builds upon this software must provide clear visible attribution to the original author ("Mirage Kit by MrKieha") in its description on all platform pages (e.g., Modrinth, CurseForge, GitHub).

Non-Commercial Use & Monetization.

• Prohibited: You CANNOT sell this mod, its derivatives, or mods directly bundling this library for a fixed price (including paywalling on Patreon, Boosty, or other stores).
• Allowed: You ARE ALLOWED to earn passive revenue from integrated platform rewards programs (such as Modrinth Creator Rewards or CurseForge Rewards Program) based on ad revenue sharing, as well as accept optional, non-paywalled donations.