Getting Started with Nebulon

Nebulon is a Fabric world-shader and visual effect library for Minecraft 1.21.11. It gives mods persistent effect handles, distance culling, GPU batching, custom GLSL render pipelines, multi-stage rendering, native dynamic lights, a pooled particle system, and optional server-authoritative syncing — all compatible with vanilla, Sodium, and Iris (including active shader packs).

---

What Nebulon provides

Area	Features
Built-in effects	Volumetric fog, snow-storm atmospheres, magic circles, arc chains, billboard sprites, SDF shapes
Particles	Pooled client particles with curves, physics, collision, attractors, and trails
Lights	Native point, spot, and beam lights with optional shadows
Networking	Server-authoritative effect and particle syncing with late-join support
Rendering	Materials, render stages, managed targets, post passes, a compositor, and render graphs
Extensibility	Custom effect types, custom GLSL, instancing, ShaderToy-style shaders, optional Effekseer backend

---

Requirements

Requirement	Version
Minecraft	1.21.11
Fabric Loader	0.19.3+
Fabric API	any
Java	21+

Sodium and Iris are optional. Nebulon detects them at runtime and never requires them.

---

Installation

Nebulon is published to the RiftRealms Maven repository. In the consuming mod's build.gradle:

repositories {
    maven {
        name = "RiftRealms"
        url = "https://maven.riftrealms.de/releases"
    }
}

dependencies {
    modImplementation "de.nexusrealms:nebulon:0.1.0-beta+mc1.21.11.20260715.123"
}

Versions follow the pattern <base>+mc<minecraft>.<yyyyMMdd>.<build number>. Check the Maven repository for the newest build.

---

Your first effect

Spawn a client-local volumetric fog volume:

VolumetricFog fog = VolumetricFog.builder(
        Vec3d.ofCenter(blockPos), new Vec3d(4, 3, 4))
    .color(ColorRgba.rgba(0x7a5cffb8))
    .density(1.4f)
    .noise(2.8f, 0.15f)
    .quality(64)
    .build();

// Spawn for 10 seconds (lifetime in ticks). Omit the lifetime for a persistent effect.
EffectHandle<VolumetricFog> handle = NebulonRendering.effects()
    .spawn(client.world, fog, 20 * 10);

// Replace the immutable description at any time.
handle.set(VolumetricFog.builder(fog.center(), new Vec3d(6, 3, 6))
    .color(fog.color())
    .build());

handle.remove();

Two one-liners for other built-ins:

NebulonRendering.effects().spawn(client.world,
    MagicCircle.simple(position, new Vec3d(0, 1, 0), 2.5, ColorRgba.rgba(0x55ccffff)));

NebulonRendering.effects().spawn(client.world,
    ArcChain.between(start, end, ColorRgba.rgba(0xff55ffff)));

Or spawn server-side and let Nebulon synchronize it to every capable client:

EffectHandle<MagicCircle> handle = NebulonNetworking.syncedEffects()
    .spawn(serverWorld, circle, 20 * 30);

Key concepts

• Effect descriptions are immutable. To change an effect, build a new description and pass it to handle.set(...) or handle.update(...).
• Handles and services are thread-safe. You may call them from any thread; GPU work always stays on the render thread.
• Lifetimes are optional. An effect spawned without a lifetime persists until its handle removes it.

---

Trying everything at once

Launch a client with the JVM flag -Dnebulon.showcase=true and join a world. Nebulon spawns a built-in gallery of fog, circles, chains, billboards, SDF shapes, pooled-particle patterns, a snow storm, and every light type in the direction the player is looking. Press F8 to toggle the live diagnostics overlay (see Diagnostics).

---

Where to go next

• Effects & built-ins — the core effect model plus fog, circles, chains, and snow storms
• Preset effects — billboards and SDF shapes without writing any GLSL
• Particles — the pooled particle system
• Dynamic lights — point, spot, and beam lighting with shadows
• Server synchronization — server-authoritative effects and particles
• Custom effects — write your own effect types and renderers
• Materials & shaders — ShaderMaterial, JSON materials, and shader-pack behavior
• Advanced rendering — targets, compositor, render graphs, instancing, ShaderToy
• Effekseer — the optional Effekseer backend contract
• Diagnostics — overlays, stats, and tuning flags