THolograms

   ⚡ 3D MINI-COMPOSITIONS  •  ZERO TICK OVERHEAD  •  FOLIA REGION-AWARE ⚡

⚡ The Architectural Paradigm Shift

Most traditional hologram plugins were written years ago around obsolete Minecraft workarounds:

• ❌ Invisible Armor Stands: Hundreds of invisible armor stands loading chunks and stressing server tick loops.
• ❌ Global O(Holograms × Players) Loops: Constantly checking distance, recalculating lines, and sending packets every tick.
• ❌ Packet Spam & De-syncs: Ghost armor stands remaining after server crashes or desyncing on chunk boundaries.
• ❌ Bloated JAR Files: 3MB to 5MB fat jars stuffed with shaded packet libraries.

🚀 How THolograms Completely Changes The Game:

Traditional Engines:                         THolograms Engine:
┌──────────────────────────────────────┐     ┌──────────────────────────────────────┐
│ [!] Global Tick Loop (Holos × Viewers)│    │ [✓] Event-Driven Spatial Culling     │
│ [!] Invisible Armor Stand Hacks      │     │ [✓] 100% Native Display Entities     │
│ [!] High Heap Allocation & Churn     │     │ [✓] Zero-Allocation Mathematical DNA │
│ [!] Server-Side Physics Overhead     │     │ [✓] Client-Side GPU Interpolation    │
│ [!] Folia Race Conditions            │     │ [✓] Strict Multi-Threaded Folia Ready│
│ [!] 3MB+ Fat JAR Bloat               │     │ [✓] ~181 KB Pure High-Performance JAR│
└──────────────────────────────────────┘     └──────────────────────────────────────┘

The Zero-Tick Rule: Static holograms and holograms with no nearby viewers execute 0.000 ms CPU per tick. Static holograms generate zero recurrent server overhead.

💎 Signature Core Innovations

1. 🧬 Motion DNA — Procedural Client Interpolation

Say goodbye to laggy server-side coordinate calculations every tick. Motion DNA computes deterministic, harmonic curves that leverage Minecraft's native client GPU interpolation:

• ELEGANT — Gentle sinusoidal vertical breathing with smooth ambient yaw rotation.
• FLOATING — Natural buoyant bobbing with subtle pitch and roll sway.
• ENERGETIC — Bouncy dynamic pulse with continuous rapid spin.
• FUTURISTIC — Quantized stepped elevation with crisp robotic transitions.
• MAGICAL — Harmonic 3D Lissajous figure-8 orbital curve.
• MECHANICAL — Linear step easing with robotic snaps.
• ORGANIC — Multi-harmonic fluid oscillation.
• NONE — Static fixed lock.

2. ⚡ 3D Mini-Compositions & AutoLayout

A hologram doesn't have to be just flat text. Build full 3D visual scenes combining MiniMessage gradient typography, floating 3D items, and voxel blocks in one composition:

• TextDisplay — MiniMessage gradients, shadows, custom background opacity, see-through wallhack mode, and billboard rotation.
• ItemDisplay — Floating 3D item models with automatic spacing.
• BlockDisplay — Full voxel block states (chests, amethyst clusters, beacons, ores).
• AutoLayout Engine — Automatically calculates exact vertical clearances (Text: 0.28m, Item: 0.60m, Block: 1.00m) so you never have to guess Y-coordinates manually!

3. 🎯 Native Responsive Interaction Hitboxes

Uses native Minecraft Interaction entities placed around the exact bounding geometry of the composition.

• Real client-side raytracing with zero passenger hacks.
• Bind Console Commands, Player Commands, Direct Chat Messages, or Sound Effects on click.

4. 🧠 Per-Player Smart Context & Placeholder Intelligence

Full optional soft-dependency integration with PlaceholderAPI (%player_name%, %vault_eco_balance%, etc.).

• Smart Refresh: Placeholders only evaluate when players are within active viewing range.
• Zero Heap Overhead: Unchanged placeholder lines do not trigger metadata packet updates.
• No PAPI? No Problem: THolograms operates completely standalone without external dependencies.

5. 🖥️ One-Line Scene DSL

Create multi-line 3D holographic scenes in one second directly in chat or console:

/tholo quick hub <rainbow><bold>WELCOME TO SKYBLOCK</bold></rainbow> | item:NETHER_STAR | <yellow>Welcome, %player_name%! | <gray>Click to open menu

6. 🎛️ Interactive GUI Editor & Clickable Chat UI

• Chest Inventory Editor (/tholo edit <id>): Live click-to-edit line text, toggle shadows, adjust see-through wallhacks, switch background presets, and nudge positions live.
• Clickable Chat Controls (/tholo list, /tholo lines <id>): Interactive [TP], [EDIT], [LINES], [▲], [▼], and [✖] buttons in chat.

7. ⏪ 20-Step Undo/Redo & Snapshot Backups

• Accidental deletion or misplacement? Rollback in one command: /tholo undo <id> or /tholo redo <id>.
• Create named configuration checkpoints: /tholo snapshot <id> <name> & /tholo restore <name> <id>.

8. 🛡️ Native Folia Multi-Threading & Adaptive Governor

• Folia Native: Uses RegionScheduler for location-bound world operations, EntityScheduler for displays, and asynchronous I/O for saving.
• Adaptive Load Governor: Continuously tracks server MSPT & TPS. Under heavy server strain, it automatically dampens animation intervals to protect gameplay performance.

🕹️ Complete Controls & Command Reference

Base aliases: /thologram, /tholo, /tholograms
Permission: tholograms.admin (Default: OP)

1. Creation & Scene DSL

2. Line Manipulation

3. Positioning & Fine-Tuning

4. Visuals & Display Entity Attributes

5. Motion DNA & Themes

6. Interactive Actions

7. Safety, Snapshots & Administration

💻 Developer API

THolograms features an enterprise-grade, fully decoupled public API.

Gradle (Kotlin DSL)

repositories {
    maven("https://repo.papermc.io/repository/maven-public/")
}

dependencies {
    compileOnly("net.tholograms:tholograms:1.0.0")
}

Maven (pom.xml)

<dependency>
    <groupId>net.tholograms</groupId>
    <artifactId>tholograms</artifactId>
    <version>1.0.0</version>
    <scope>provided</scope>
</dependency>

Java Usage

import net.tholograms.api.THolograms;
import net.tholograms.api.Hologram;
import net.tholograms.animation.MotionStyle;
import org.bukkit.Material;
import org.bukkit.Location;

// Create a 3D composite hologram programmatically
Hologram hologram = THolograms.getAPI().builder("hub-welcome")
    .location(player.getLocation().add(0, 1.2, 0))
    .text("<gradient:#FFD700:#FFF3A0><bold>WELCOME TO SKYBLOCK</bold></gradient>")
    .text("<gray>Welcome, <gold>%player_name%</gold>!")
    .item(Material.NETHER_STAR)
    .lineSpacing(0.32f)
    .motion(MotionStyle.ELEGANT)
    .viewDistance(48.0)
    .build();

📊 Technical Specifications & Benchmarks

📜 Permissions

• tholograms.admin — Full administrative control over all THolograms commands (Default: OP).
• tholograms.use — Allows players to interact with click hitboxes (Default: True for all players).