Mixin System

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/kamp0010/voxy_worldgen_v2/llms.txt

Use this file to discover all available pages before exploring further.

​

Overview

• Track block updates for LOD synchronization
• Intercept chunk saves to prevent unnecessary disk writes
• Access internal Minecraft APIs
• Integrate with chunk loading systems

​

Core Mixins

​

BlockUpdateMixin

@Inject(method = "sendBlockUpdated", at = @At("TAIL"))
private void onBlockUpdated(BlockPos pos, BlockState oldState, BlockState newState, int flags, CallbackInfo ci) {
    ServerLevel self = (ServerLevel) (Object) this;
    
    LevelChunk chunk = self.getChunkAt(pos);
    if (chunk != null) {
        ChunkUpdateTracker.getInstance().markDirty(chunk);
    }
}

• Hooks into Minecraft’s block update system
• Marks the containing chunk as dirty via ChunkUpdateTracker
• Ensures LOD clients receive updates when terrain changes

​

ChunkSaveMixin

@Inject(method = "save", at = @At("HEAD"), cancellable = true)
private void voxyworldgen$onSave(ChunkAccess chunk, CallbackInfoReturnable<Boolean> cir) {
    if (Config.DATA.saveNormalChunks) return;

    ChunkPos pos = chunk.getPos();
    LodChunkTracker tracker = LodChunkTracker.getInstance();

    if (!tracker.isLodOnly(this.level.dimension(), pos.toLong())) return;

    if (ChunkGenerationManager.getInstance().isAnyPlayerNear(this.level.dimension(), pos)) {
        tracker.unmark(this.level.dimension(), pos.toLong());
        return;
    }

    tracker.unmark(this.level.dimension(), pos.toLong());
    ((ChunkAccessUnsavedMixin) chunk).voxyworldgen$setUnsaved(false);
    cir.setReturnValue(false);
}

1. Checks if the chunk was marked as “LOD-only” (generated for distant viewing)
2. If a player is within view distance, allows the save to proceed normally
3. Otherwise, clears the dirty flag and suppresses the save operation
4. Returns false to indicate the chunk was not saved

​

ChunkAccessUnsavedMixin

@Mixin(ChunkAccess.class)
public interface ChunkAccessUnsavedMixin {
    @Accessor("unsaved")
    void voxyworldgen$setUnsaved(boolean unsaved);
}

• Provides write access to the internal unsaved field
• Used by ChunkSaveMixin to clear dirty flags on LOD-only chunks
• Prevents C2ME and vanilla systems from repeatedly attempting to save suppressed chunks

​

ChunkMapMixin

@Mixin(ChunkMap.class)
public interface ChunkMapMixin {
    @Invoker("tick")
    void invokeTick(BooleanSupplier booleanSupplier);

    @Invoker("readChunk")
    CompletableFuture<Optional<CompoundTag>> invokeReadChunk(ChunkPos pos);
}

• Exposes tick() for manual chunk system updates (legacy, not currently used)
• Exposes readChunk() for asynchronously reading chunk NBT data from disk

​

MinecraftServerAccess

@Mixin(MinecraftServer.class)
public interface MinecraftServerAccess {
    @Accessor("emptyTicks")
    void setEmptyTicks(int ticks);
}

• Provides write access to emptyTicks counter
• Reset to 0 after each chunk completes to prevent “server stopping due to inactivity”
• Ensures servers with stop-when-empty=true don’t shut down during background generation

​

MinecraftServerMixin

@Mixin(MinecraftServer.class)
public abstract class MinecraftServerMixin implements MinecraftServerExtension {
    @Override
    public void voxyworldgen$runHousekeeping(BooleanSupplier haveTime) {
        // removed to prevent conflicts with async/c2me mods
    }

    @Override
    public void voxyworldgen$markHousekeeping() {
        // no longer used
    }
}

• Implements the MinecraftServerExtension interface
• Methods are no-ops to maintain compatibility
• Previously used for manual chunk system ticking, now handled differently

​

ServerChunkCacheMixin

@Mixin(ServerChunkCache.class)
public interface ServerChunkCacheMixin {
    @Invoker("getChunkFutureMainThread")
    CompletableFuture<ChunkResult<ChunkAccess>> invokeGetChunkFutureMainThread(
        int x, int z, ChunkStatus status, boolean create
    );

    @Invoker
    boolean invokeRunDistanceManagerUpdates();
}

• getChunkFutureMainThread: Initiates asynchronous chunk generation to a specific status
• runDistanceManagerUpdates: Flushes pending ticket operations (load/unload tickets)

• Chunk generation: ChunkGenerationManager.workerLoop() /workspace/source/src/main/java/com/ethan/voxyworldgenv2/core/ChunkGenerationManager.java:318
• Ticket processing: ChunkGenerationManager.processPendingTickets() /workspace/source/src/main/java/com/ethan/voxyworldgenv2/core/ChunkGenerationManager.java:512

​

ServerLevelMixin

@Mixin(ServerLevel.class)
public interface ServerLevelMixin {
    @Accessor
    PersistentEntitySectionManager<Entity> getEntityManager();
}

• Provides read access to the internal entity manager
• Used for advanced entity processing in LOD chunks (if needed)
• Currently available but not actively used in core functionality

​

Mixin Categories

​

Accessor Mixins

• ChunkAccessUnsavedMixin - chunk dirty state
• MinecraftServerAccess - empty tick counter
• ServerLevelMixin - entity manager

​

Invoker Mixins

• ChunkMapMixin - chunk reading and ticking
• ServerChunkCacheMixin - chunk loading and distance updates

​

Injection Mixins

• BlockUpdateMixin - block update tracking
• ChunkSaveMixin - save interception
• MinecraftServerMixin - extension interface

​

Thread Safety Considerations

​

Thread-Safe Mixins

• ChunkSaveMixin - reads from concurrent maps only
• All accessor/invoker mixins - safe when called from appropriate threads

​

Main-Thread-Only Mixins

• BlockUpdateMixin - always runs on server thread

​

Debugging Mixin Issues

1. Check Mixin Logs: Look for mixin application errors in logs/latest.log
2. Verify Fabric Loader Version: Ensure you’re using a recent Fabric Loader (0.15.0+)
3. Check for Conflicts: Other mods targeting the same methods can cause conflicts
4. Review Mixin JSON: The voxyworldgenv2.mixins.json defines all mixin targets

​

Related Documentation

• Events - How events integrate with the mixin system
• Distance Graph - The chunk prioritization system that benefits from these mixins
• Configuration - Settings that control mixin behavior (saveNormalChunks)