com.hypixel.hytale/
├── assetstore/        # Asset loading, registries, and packs (~50 classes)
├── builtin/           # 43 builtin gameplay modules (1,757 classes)
├── codec/             # Serialization framework (165 classes)
├── common/            # Shared utilities (62 classes)
├── component/         # ECS implementation (~100 classes)
├── event/             # Event bus system (23 classes)
├── function/          # Functional interfaces (34 classes)
├── logger/            # Logging framework (17 classes)
├── math/              # Vector/matrix math (95 classes)
├── metrics/           # Performance monitoring (12 classes)
├── plugin/            # Early plugin loader (3 classes)
├── procedurallib/     # Noise & procedural generation (257 classes)
├── protocol/          # Network packets (737 classes)
├── registry/          # Registration framework (3 classes)
├── server/            # Server implementation (3,807 classes)
├── sneakythrow/       # Exception utilities
├── storage/           # Persistence layer (~20 classes)
└── unsafe/            # Low-level utilities

public interface IBaseEvent<KeyType> {}

public interface IEvent<KeyType> extends IBaseEvent<KeyType> {}

public interface IAsyncEvent<KeyType> extends IBaseEvent<KeyType> {}

public interface ICancellable {
    boolean isCancelled();
    void setCancelled(boolean cancelled);
}

public interface IProcessedEvent {
    void processEvent(@Nonnull String hookName);
}

public interface IEventBus extends IEventRegistry {
    // Synchronous dispatch (no key)
    <KeyType, EventType extends IEvent<KeyType>> EventType dispatch(
        @Nonnull Class<EventType> eventClass);

    // Synchronous dispatch (with key)
    <KeyType, EventType extends IEvent<KeyType>> IEventDispatcher<EventType, EventType>
        dispatchFor(@Nonnull Class<? super EventType> eventClass, @Nullable KeyType key);

    // Asynchronous dispatch (no key)
    <EventType extends IAsyncEvent<Void>> CompletableFuture<EventType> dispatchAsync(
        @Nonnull Class<EventType> eventClass);

    // Asynchronous dispatch (with key)
    <KeyType, EventType extends IAsyncEvent<KeyType>>
        IEventDispatcher<EventType, CompletableFuture<EventType>>
        dispatchForAsync(@Nonnull Class<? super EventType> eventClass, @Nullable KeyType key);
}

public class EventBus implements IEventBus {
    @Nonnull
    private final Map<Class<? extends IBaseEvent<?>>, EventBusRegistry<?, ?, ?>> registryMap;
    private final boolean timeEvents;

    public EventBus(boolean timeEvents);

    public void shutdown();

    @Nonnull
    public Set<Class<? extends IBaseEvent<?>>> getRegisteredEventClasses();

    @Nonnull
    public Set<String> getRegisteredEventClassNames();

    @Nullable
    public EventBusRegistry<?, ?, ?> getRegistry(@Nonnull String eventName);

    @Nonnull
    public <KeyType, EventType extends IBaseEvent<KeyType>> EventBusRegistry<KeyType, EventType, ?>
        getRegistry(@Nonnull Class<? super EventType> eventClass);
}

public interface IEventRegistry {
    // ===== SYNCHRONOUS REGISTRATION (6 overloads) =====

    // Basic registration (default priority)
    @Nullable
    <KeyType, EventType extends IEvent<KeyType>> EventRegistration<KeyType, EventType>
        register(Class<EventType> eventClass, Consumer<EventType> handler);

    // With EventPriority enum
    @Nullable
    <KeyType, EventType extends IEvent<KeyType>> EventRegistration<KeyType, EventType>
        register(EventPriority priority, Class<EventType> eventClass, Consumer<EventType> handler);

    // With raw priority value
    @Nullable
    <KeyType, EventType extends IEvent<KeyType>> EventRegistration<KeyType, EventType>
        register(short priority, Class<EventType> eventClass, Consumer<EventType> handler);

    // With key (default priority)
    @Nullable
    <KeyType, EventType extends IEvent<KeyType>> EventRegistration<KeyType, EventType>
        register(Class<EventType> eventClass, KeyType key, Consumer<EventType> handler);

    // With key and EventPriority
    @Nullable
    <KeyType, EventType extends IEvent<KeyType>> EventRegistration<KeyType, EventType>
        register(EventPriority priority, Class<EventType> eventClass, KeyType key, Consumer<EventType> handler);

    // With key and raw priority
    @Nullable
    <KeyType, EventType extends IEvent<KeyType>> EventRegistration<KeyType, EventType>
        register(short priority, Class<EventType> eventClass, KeyType key, Consumer<EventType> handler);

    // ===== ASYNCHRONOUS REGISTRATION (6 overloads) =====

    @Nullable
    <KeyType, EventType extends IAsyncEvent<KeyType>> EventRegistration<KeyType, EventType>
        registerAsync(Class<EventType> eventClass,
            Function<CompletableFuture<EventType>, CompletableFuture<EventType>> handler);

    // ... (same pattern as sync with priority and key variants)

    // ===== GLOBAL REGISTRATION (all keys) =====
    @Nullable
    <KeyType, EventType extends IEvent<KeyType>> EventRegistration<KeyType, EventType>
        registerGlobal(Class<EventType> eventClass, Consumer<EventType> handler);

    @Nullable
    <KeyType, EventType extends IEvent<KeyType>> EventRegistration<KeyType, EventType>
        registerGlobal(EventPriority priority, Class<EventType> eventClass, Consumer<EventType> handler);

    // ===== UNHANDLED FALLBACK REGISTRATION =====
    @Nullable
    <KeyType, EventType extends IEvent<KeyType>> EventRegistration<KeyType, EventType>
        registerUnhandled(Class<EventType> eventClass, Consumer<EventType> handler);
}

public class EventRegistration<KeyType, EventType extends IBaseEvent<KeyType>>
    extends Registration {

    @Nonnull
    protected final Class<EventType> eventClass;

    public EventRegistration(
        @Nonnull Class<EventType> eventClass,
        @Nonnull BooleanSupplier isEnabled,
        @Nonnull Runnable unregister);

    public EventRegistration(
        @Nonnull EventRegistration<KeyType, EventType> registration,
        @Nonnull BooleanSupplier isEnabled,
        @Nonnull Runnable unregister);

    @Nonnull
    public Class<EventType> getEventClass();

    @Nonnull
    @Override
    public String toString();

    @Nonnull
    @SafeVarargs
    public static <KeyType, EventType extends IBaseEvent<KeyType>>
        EventRegistration<KeyType, EventType> combine(
            @Nonnull EventRegistration<KeyType, EventType> first,
            @Nonnull EventRegistration<KeyType, EventType>... others);
}

public enum EventPriority {
    // Values range from -32768 to 32767 (short)
    // Default priority is 0

    public short getValue();
}

// Using enum
eventBus.register(EventPriority.HIGH, MyEvent.class, handler);

// Using raw priority values
eventBus.register((short) -100, MyEvent.class, handler);  // Execute early
eventBus.register((short) 100, MyEvent.class, handler);   // Execute late

public interface IEventDispatcher<EventType extends IBaseEvent, ReturnType> {
    default boolean hasListener() {
        return true;
    }

    ReturnType dispatch(@Nullable EventType event);
}

IEventBus eventBus = server.getEventBus();

// Simple registration (default priority)
eventBus.register(PlayerJoinEvent.class, event -> {
    Player player = event.getPlayer();
    player.sendMessage("Welcome!");
});

// With priority (executes before normal handlers)
eventBus.register(EventPriority.HIGH, PlayerJoinEvent.class, event -> {
    // Early processing
});

// Key-scoped registration (only for specific key)
eventBus.register(BlockBreakEvent.class, specificBlockType, event -> {
    // Only handles events for specificBlockType
});

// Global registration (receives all keys)
eventBus.registerGlobal(BlockBreakEvent.class, event -> {
    // Handles all block break events regardless of block type
});

eventBus.registerAsync(AsyncDataLoadEvent.class, future -> {
    return future.thenApply(event -> {
        // Process asynchronously
        loadDataFromDatabase(event);
        return event;
    });
});

// Synchronous dispatch (simple)
PlayerJoinEvent event = eventBus.dispatch(PlayerJoinEvent.class);

// With custom event instance via dispatcher
IEventDispatcher<PlayerJoinEvent, PlayerJoinEvent> dispatcher =
    eventBus.dispatchFor(PlayerJoinEvent.class, null);
PlayerJoinEvent result = dispatcher.dispatch(new PlayerJoinEvent(player));

// Asynchronous dispatch
CompletableFuture<AsyncEvent> future = eventBus.dispatchAsync(AsyncEvent.class);
future.thenAccept(event -> handleResult(event));

// Check if dispatcher has listeners before creating expensive event
IEventDispatcher<ExpensiveEvent, ExpensiveEvent> expensiveDispatcher =
    eventBus.dispatchFor(ExpensiveEvent.class, null);
if (expensiveDispatcher.hasListener()) {
    expensiveDispatcher.dispatch(createExpensiveEvent());
}

public class BlockBreakEvent implements IEvent<BlockType>, ICancellable {
    private final Player player;
    private final BlockType blockType;
    private final Vector3i position;
    private boolean cancelled = false;

    public BlockBreakEvent(Player player, BlockType blockType, Vector3i position) {
        this.player = player;
        this.blockType = blockType;
        this.position = position;
    }

    @Override
    public boolean isCancelled() {
        return cancelled;
    }

    @Override
    public void setCancelled(boolean cancelled) {
        this.cancelled = cancelled;
    }

    public Player getPlayer() { return player; }
    public BlockType getBlockType() { return blockType; }
    public Vector3i getPosition() { return position; }
}

// Handler that cancels the event
eventBus.register(BlockBreakEvent.class, event -> {
    if (isProtectedBlock(event.getPosition())) {
        event.setCancelled(true);
        event.getPlayer().sendMessage("You cannot break this block!");
    }
});

// Store the registration
EventRegistration<?, ?> registration = eventBus.register(MyEvent.class, handler);

// Later, unregister
registration.unregister();

// Check if still registered
if (registration.isRegistered()) {
    // Still active
}

public abstract class EventBusRegistry<KeyType, EventType extends IBaseEvent<KeyType>,
    ConsumerMapType extends EventBusRegistry.EventConsumerMap<...>> {

    @Nonnull
    protected static final Object NULL = new Object();  // Sentinel for null keys

    @Nonnull
    protected final HytaleLogger logger;

    @Nonnull
    protected final Class<EventType> eventClass;

    @Nonnull
    protected final Map<KeyType, ConsumerMapType> map;  // ConcurrentHashMap

    @Nonnull
    protected final ConsumerMapType global;  // Global handlers

    @Nonnull
    protected final ConsumerMapType unhandled;  // Fallback handlers

    protected boolean timeEvents;
    protected boolean shutdown;

    @Nonnull
    public Class<EventType> getEventClass();

    public boolean isTimeEvents();
    public void setTimeEvents(boolean timeEvents);

    public void shutdown();
    public boolean isAlive();

    public abstract EventRegistration<KeyType, EventType> register(
        short priority, @Nullable KeyType key, @Nonnull Consumer<EventType> consumer);

    public abstract EventRegistration<KeyType, EventType> registerGlobal(
        short priority, @Nonnull Consumer<EventType> consumer);

    public abstract EventRegistration<KeyType, EventType> registerUnhandled(
        short priority, @Nonnull Consumer<EventType> consumer);

    public abstract IEventDispatcher<EventType, ?> dispatchFor(KeyType key);
}

public static abstract class EventConsumer {
    @Nonnull
    protected static final AtomicInteger consumerIndex = new AtomicInteger();

    protected final int index;           // Unique consumer ID
    protected final short priority;      // Execution priority

    @Nonnull
    protected final String consumerString;  // Handler description

    @Nonnull
    protected final Metric timer = new Metric();  // Performance tracking

    public EventConsumer(short priority, @Nonnull String consumerString);

    public int getIndex();
    public short getPriority();

    @Nonnull
    public String getConsumerString();

    @Nonnull
    public Metric getTimer();
}

public static abstract class EventConsumerMap<EventType extends IBaseEvent,
    ConsumerType extends EventBusRegistry.EventConsumer, ReturnType>
    implements IEventDispatcher<EventType, ReturnType> {

    private static final short[] EMPTY_SHORT_ARRAY = new short[0];

    private final AtomicReference<short[]> prioritiesRef =
        new AtomicReference<>(EMPTY_SHORT_ARRAY);

    @Nonnull
    private final Short2ObjectConcurrentHashMap<List<ConsumerType>> map =
        new Short2ObjectConcurrentHashMap(true, -32768);

    public boolean isEmpty();

    public void add(@Nonnull ConsumerType eventConsumer);
    public boolean remove(@Nonnull ConsumerType consumer);

    public short[] getPriorities();

    @Nullable
    public List<ConsumerType> get(short priority);
}

public class SyncEventConsumer<EventType extends IEvent>
    extends EventBusRegistry.EventConsumer {

    @Nonnull
    private final Consumer<EventType> consumer;

    @Nonnull
    private final Consumer<EventType> timedConsumer;

    public SyncEventConsumer(short priority, @Nonnull Consumer<EventType> consumer);

    @Nonnull
    protected Consumer<EventType> getConsumer();

    @Nonnull
    public Consumer<EventType> getTimedConsumer();
}

public class AsyncEventConsumer<EventType extends IAsyncEvent>
    extends EventBusRegistry.EventConsumer {

    @Nonnull
    private final Function<CompletableFuture<EventType>, CompletableFuture<EventType>> function;

    @Nonnull
    private final Function<CompletableFuture<EventType>, CompletableFuture<EventType>> timedFunction;

    public AsyncEventConsumer(
        short priority,
        @Nonnull String consumerString,
        @Nonnull Function<CompletableFuture<EventType>, CompletableFuture<EventType>> function);

    @Nonnull
    public Function<CompletableFuture<EventType>, CompletableFuture<EventType>> getFunction();

    @Nonnull
    public Function<CompletableFuture<EventType>, CompletableFuture<EventType>> getTimedFunction();
}

package com.hypixel.hytale.plugin.early;

import javax.annotation.Nonnull;
import javax.annotation.Nullable;

public interface ClassTransformer {
    /**
     * Returns the priority of this transformer.
     * Higher values execute first (descending order).
     *
     * @return priority (default: 0)
     */
    default int priority() {
        return 0;
    }

    /**
     * Transform class bytecode.
     *
     * @param className Binary class name (e.g., "com.hypixel.MyClass")
     * @param internalName Internal name (e.g., "com/hypixel/MyClass")
     * @param classBytes Original bytecode
     * @return Transformed bytecode, or null to skip transformation
     */
    @Nullable
    byte[] transform(
        @Nonnull String className,
        @Nonnull String internalName,
        @Nonnull byte[] classBytes);
}

package com.hypixel.hytale.plugin.early;

import java.net.URLClassLoader;
import java.nio.file.Path;
import java.util.List;

public final class EarlyPluginLoader {
    /**
     * Default plugin directory.
     */
    public static final Path EARLY_PLUGINS_PATH = Path.of("earlyplugins");

    /**
     * Static list of loaded transformers.
     */
    private static final List<ClassTransformer> transformers;

    /**
     * ClassLoader for plugin classes.
     */
    @Nullable
    private static URLClassLoader pluginClassLoader;

    /**
     * Loads early plugins from the default directory and command-line paths.
     *
     * Process:
     * 1. Collects JARs from earlyplugins/
     * 2. Collects JARs from --early-plugins paths
     * 3. Creates URLClassLoader with discovered JARs
     * 4. Uses ServiceLoader to find ClassTransformer implementations
     * 5. Sorts transformers by priority (descending)
     * 6. Requires user confirmation (unless --singleplayer or --accept-early-plugins)
     *
     * @param args Command-line arguments
     */
    public static void loadEarlyPlugins(String[] args);

    /**
     * @return true if any transformers are loaded
     */
    public static boolean hasTransformers();

    /**
     * @return Unmodifiable list of loaded transformers
     */
    public static List<ClassTransformer> getTransformers();

    /**
     * @return The plugin ClassLoader, or null if not initialized
     */
    @Nullable
    public static URLClassLoader getPluginClassLoader();
}

package com.hypixel.hytale.plugin.early;

import java.net.URL;
import java.net.URLClassLoader;
import java.util.List;
import java.util.Set;
import javax.annotation.Nonnull;

public final class TransformingClassLoader extends URLClassLoader {
    /**
     * Protected packages that cannot be transformed (security boundary).
     */
    private static final Set<String> SECURE_PACKAGE_PREFIXES = Set.of(
        "java.",
        "javax.",
        "jdk.",
        "sun.",
        "com.sun.",
        "org.bouncycastle.",
        "server.io.netty.",
        "org.objectweb.asm.",
        "com.google.gson.",
        "org.slf4j.",
        "org.apache.logging.",
        "ch.qos.logback.",
        "com.google.flogger.",
        "server.io.sentry.",
        "com.hypixel.protoplus.",
        "com.hypixel.fastutil.",
        "com.hypixel.hytale.plugin.early."
    );

    @Nonnull
    private final List<ClassTransformer> transformers;

    @Nonnull
    private final ClassLoader appClassLoader;

    /**
     * @param urls Plugin JAR URLs
     * @param transformers Transformers to apply
     * @param parent Parent ClassLoader
     * @param appClassLoader App's original ClassLoader for secure classes
     */
    public TransformingClassLoader(
        @Nonnull URL[] urls,
        @Nonnull List<ClassTransformer> transformers,
        ClassLoader parent,
        ClassLoader appClassLoader);

    /**
     * Loads a class, applying transformers if not a secure package.
     *
     * Process:
     * 1. Check if already loaded (cache)
     * 2. If preloaded class → delegate to appClassLoader
     * 3. If in plugin JARs → transform bytecode
     * 4. Otherwise → delegate to parent
     *
     * @param name Binary class name
     * @param resolve Whether to resolve the class
     * @return Loaded class
     * @throws ClassNotFoundException if class not found
     */
    @Override
    protected Class<?> loadClass(String name, boolean resolve)
        throws ClassNotFoundException;
}

package com.mymod;

import com.hypixel.hytale.plugin.early.ClassTransformer;
import org.objectweb.asm.*;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;

public class MyTransformer implements ClassTransformer {

    @Override
    public int priority() {
        return 100;  // Higher = executed first
    }

    @Nullable
    @Override
    public byte[] transform(
            @Nonnull String className,
            @Nonnull String internalName,
            @Nonnull byte[] classBytes) {

        // Only transform specific classes
        if (!className.equals("com.hypixel.hytale.server.SomeClass")) {
            return null;  // No transformation
        }

        // Use ASM to transform bytecode
        ClassReader reader = new ClassReader(classBytes);
        ClassWriter writer = new ClassWriter(reader, ClassWriter.COMPUTE_FRAMES);

        ClassVisitor visitor = new ClassVisitor(Opcodes.ASM9, writer) {
            @Override
            public MethodVisitor visitMethod(int access, String name, String descriptor,
                                            String signature, String[] exceptions) {
                MethodVisitor mv = super.visitMethod(access, name, descriptor, signature, exceptions);

                if (name.equals("targetMethod")) {
                    return new MethodVisitor(Opcodes.ASM9, mv) {
                        @Override
                        public void visitCode() {
                            super.visitCode();
                            // Add code at method start
                            mv.visitFieldInsn(Opcodes.GETSTATIC, "java/lang/System", "out",
                                            "Ljava/io/PrintStream;");
                            mv.visitLdcInsn("Method called!");
                            mv.visitMethodInsn(Opcodes.INVOKEVIRTUAL, "java/io/PrintStream",
                                             "println", "(Ljava/lang/String;)V", false);
                        }
                    };
                }
                return mv;
            }
        };

        reader.accept(visitor, 0);
        return writer.toByteArray();
    }
}

com.mymod.MyTransformer

{
    "group": "com.mymod",
    "name": "MyMod",
    "version": "1.0.0",
    "description": "My awesome mod",
    "authors": [
        {
            "name": "MyName",
            "email": "me@example.com"
        }
    ],
    "main": "com.mymod.MyTransformer"
}

<!-- pom.xml -->
<project>
    <groupId>com.mymod</groupId>
    <artifactId>mymod</artifactId>
    <version>1.0.0</version>
    <packaging>jar</packaging>

    <dependencies>
        <dependency>
            <groupId>org.ow2.asm</groupId>
            <artifactId>asm</artifactId>
            <version>9.5</version>
        </dependency>
    </dependencies>

    <build>
        <resources>
            <resource>
                <directory>src/main/resources</directory>
                <includes>
                    <include>META-INF/services/**</include>
                </includes>
            </resource>
        </resources>
    </build>
</project>

[EarlyPlugin] Found: my-mod.jar
[EarlyPlugin] Loading transformer: com.mymod.MyTransformer (priority=100)

package com.hypixel.hytale.component;

import javax.annotation.Nullable;

public interface Component<ECS_TYPE> extends Cloneable {
    /**
     * Clone this component.
     * @return Cloned component, or null if not cloneable
     */
    @Nullable
    Component<ECS_TYPE> clone();

    /**
     * Clone for serialization purposes.
     * Default implementation delegates to clone().
     * @return Cloned component suitable for serialization
     */
    @Nullable
    default Component<ECS_TYPE> cloneSerializable() {
        return clone();
    }
}

/**
 * Marker component that prevents serialization.
 * Add to entities that should not be persisted.
 */
public final class NonSerialized<ECS_TYPE> implements Component<ECS_TYPE> {
    public static final NonSerialized<?> INSTANCE = new NonSerialized<>();

    @Override
    public Component<ECS_TYPE> clone() {
        return this;  // Singleton
    }
}

/**
 * Marker component that prevents ticking.
 * Add to entities that should not be processed by ticking systems.
 */
public final class NonTicking<ECS_TYPE> implements Component<ECS_TYPE> {
    public static final NonTicking<?> INSTANCE = new NonTicking<>();

    @Override
    public Component<ECS_TYPE> clone() {
        return this;  // Singleton
    }
}

package com.hypixel.hytale.component;

import javax.annotation.Nullable;

/**
 * Global singleton resource accessible throughout the ECS.
 * Unlike components, resources are not attached to entities.
 */
public interface Resource<ECS_TYPE> extends Cloneable {
    /**
     * Clone this resource.
     * @return Cloned resource, or null if not cloneable
     */
    @Nullable
    Resource<ECS_TYPE> clone();
}

package com.hypixel.hytale.component;

/**
 * Opaque reference to an entity.
 * Safe handle that detects invalid references when entity is deleted.
 */
public class Ref<ECS_TYPE> {
    private final Store<ECS_TYPE> store;
    private volatile int index;
    private volatile int hashCode;
    private volatile Throwable invalidatedBy;

    /**
     * @return The store containing this entity
     */
    public Store<ECS_TYPE> getStore();

    /**
     * @return The entity index in the store
     */
    public int getIndex();

    /**
     * @return true if this reference is still valid
     */
    public boolean isValid();

    /**
     * Validates this reference.
     * @throws IllegalStateException if reference is invalid
     */
    public void validate() throws IllegalStateException;

    /**
     * Marks this reference as invalid (entity deleted).
     */
    public void invalidate();
}

package com.hypixel.hytale.component;

import java.util.concurrent.locks.StampedLock;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;

/**
 * Entity data template before adding to store.
 * Thread-safe with StampedLock for concurrent access.
 */
public class Holder<ECS_TYPE> {
    private final StampedLock lock = new StampedLock();
    private Archetype<ECS_TYPE> archetype;
    private Component<ECS_TYPE>[] components;
    private boolean ensureValidComponents = true;

    /**
     * Create holder with a component.
     * @param type Component type
     * @param component Component instance
     * @return this holder for chaining
     */
    @Nonnull
    public <T extends Component<ECS_TYPE>> Holder<ECS_TYPE> with(
        ComponentType<ECS_TYPE, T> type, T component);

    /**
     * Get component from holder.
     * @param type Component type
     * @return Component instance, or null if not present
     */
    @Nullable
    public <T extends Component<ECS_TYPE>> T get(ComponentType<ECS_TYPE, T> type);

    /**
     * @return The archetype of this holder
     */
    @Nonnull
    public Archetype<ECS_TYPE> getArchetype();
}

package com.hypixel.hytale.component;

import java.util.concurrent.CompletableFuture;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;

/**
 * Main ECS container managing all entities, components, and resources.
 * Thread-safe and optimized for high-performance entity processing.
 */
public class Store<ECS_TYPE> implements ComponentAccessor<ECS_TYPE> {
    private final ComponentRegistry<ECS_TYPE> registry;
    private final ECS_TYPE externalData;
    private final IResourceStorage resourceStorage;

    // ===== ENTITY MANAGEMENT =====

    /**
     * Add entity from holder.
     * @param holder Entity template
     * @return Reference to new entity
     */
    @Nonnull
    public Ref<ECS_TYPE> addEntity(Holder<ECS_TYPE> holder);

    /**
     * Add entity with reason.
     * @param holder Entity template
     * @param reason Why entity is being added
     * @return Reference to new entity
     */
    @Nonnull
    public Ref<ECS_TYPE> addEntity(Holder<ECS_TYPE> holder, AddReason reason);

    /**
     * Add multiple entities.
     * @param holders Entity templates
     * @param reason Why entities are being added
     * @return References to new entities
     */
    @Nonnull
    public Ref<ECS_TYPE>[] addEntities(Holder<ECS_TYPE>[] holders, AddReason reason);

    /**
     * Remove entity from store.
     * @param ref Entity reference
     * @param reason Why entity is being removed
     * @return Holder containing entity's components (for potential transfer)
     */
    @Nullable
    public Holder<ECS_TYPE> removeEntity(Ref<ECS_TYPE> ref, RemoveReason reason);

    // ===== COMPONENT ACCESS =====

    /**
     * Get component from entity.
     * @param ref Entity reference
     * @param type Component type
     * @return Component instance, or null if not present
     */
    @Nullable
    @Override
    public <T extends Component<ECS_TYPE>> T getComponent(
        Ref<ECS_TYPE> ref, ComponentType<ECS_TYPE, T> type);

    /**
     * Get component, creating default if not present.
     * @param ref Entity reference
     * @param type Component type
     * @return Component instance (never null)
     */
    @Nonnull
    @Override
    public <T extends Component<ECS_TYPE>> T ensureAndGetComponent(
        Ref<ECS_TYPE> ref, ComponentType<ECS_TYPE, T> type);

    /**
     * Set component on entity (replaces existing).
     * @param ref Entity reference
     * @param type Component type
     * @param value Component instance
     */
    @Override
    public <T extends Component<ECS_TYPE>> void putComponent(
        Ref<ECS_TYPE> ref, ComponentType<ECS_TYPE, T> type, T value);

    /**
     * Add component to entity.
     * @param ref Entity reference
     * @param type Component type
     * @param value Component instance
     */
    @Override
    public <T extends Component<ECS_TYPE>> void addComponent(
        Ref<ECS_TYPE> ref, ComponentType<ECS_TYPE, T> type, T value);

    /**
     * Add component using default supplier.
     * @param ref Entity reference
     * @param type Component type
     * @return Created component
     */
    @Nonnull
    @Override
    public <T extends Component<ECS_TYPE>> T addComponent(
        Ref<ECS_TYPE> ref, ComponentType<ECS_TYPE, T> type);

    /**
     * Remove component from entity.
     * @param ref Entity reference
     * @param type Component type
     */
    @Override
    public <T extends Component<ECS_TYPE>> void removeComponent(
        Ref<ECS_TYPE> ref, ComponentType<ECS_TYPE, T> type);

    /**
     * Try to remove component (no error if not present).
     * @param ref Entity reference
     * @param type Component type
     */
    @Override
    public <T extends Component<ECS_TYPE>> void tryRemoveComponent(
        Ref<ECS_TYPE> ref, ComponentType<ECS_TYPE, T> type);

    // ===== RESOURCE ACCESS =====

    /**
     * Get global resource.
     * @param type Resource type
     * @return Resource instance
     */
    @Override
    public <T extends Resource<ECS_TYPE>> T getResource(ResourceType<ECS_TYPE, T> type);

    /**
     * @return External data associated with this store
     */
    @Override
    public ECS_TYPE getExternalData();

    // ===== ARCHETYPE =====

    /**
     * Get entity's archetype.
     * @param ref Entity reference
     * @return Archetype describing entity's components
     */
    @Override
    public Archetype<ECS_TYPE> getArchetype(Ref<ECS_TYPE> ref);

    // ===== EVENTS =====

    /**
     * Invoke event on entity.
     * @param ref Target entity
     * @param event Event instance
     */
    @Override
    public <Event extends EcsEvent> void invoke(Ref<ECS_TYPE> ref, Event event);

    /**
     * Invoke entity event with explicit type.
     * @param type Event type
     * @param ref Target entity
     * @param event Event instance
     */
    @Override
    public <Event extends EcsEvent> void invoke(
        EntityEventType<ECS_TYPE, Event> type, Ref<ECS_TYPE> ref, Event event);

    /**
     * Invoke world-wide event.
     * @param event Event instance
     */
    @Override
    public <Event extends EcsEvent> void invoke(Event event);

    /**
     * Invoke world event with explicit type.
     * @param type Event type
     * @param event Event instance
     */
    @Override
    public <Event extends EcsEvent> void invoke(
        WorldEventType<ECS_TYPE, Event> type, Event event);

    // ===== COMMAND BUFFER =====

    /**
     * Create command buffer for deferred operations.
     * Useful during iteration to avoid concurrent modification.
     * @return New command buffer
     */
    @Nonnull
    public CommandBuffer<ECS_TYPE> fork();

    // ===== SYSTEM TICK =====

    /**
     * Execute all registered systems.
     * Called each game tick.
     */
    public void tick();
}

package com.hypixel.hytale.component;

import javax.annotation.Nonnull;

/**
 * Represents a specific combination of component types.
 * Immutable snapshot used for entity categorization and queries.
 */
public class Archetype<ECS_TYPE> implements Query<ECS_TYPE> {
    private final int minIndex;
    private final int count;
    private final ComponentType<ECS_TYPE, ?>[] componentTypes;

    /**
     * @return Empty archetype singleton
     */
    @Nonnull
    public static <ECS_TYPE> Archetype<ECS_TYPE> empty();

    /**
     * @return Minimum component index in this archetype
     */
    public int getMinIndex();

    /**
     * @return Number of components in this archetype
     */
    public int count();

    /**
     * @return Array length (may be larger than count for sparse storage)
     */
    public int length();

    /**
     * Get component type by index.
     * @param index Component index
     * @return Component type at index
     */
    public ComponentType<ECS_TYPE, ?> get(int index);

    @Override
    public boolean test(Archetype<ECS_TYPE> archetype) {
        // Tests if this archetype matches the query
        return true;
    }
}

package com.hypixel.hytale.component;

import javax.annotation.Nonnull;

/**
 * Cache-efficient storage for entities sharing the same archetype.
 * Uses Struct-of-Arrays (SoA) layout for optimal memory access patterns.
 */
public class ArchetypeChunk<ECS_TYPE> {
    protected final Store<ECS_TYPE> store;
    protected final Archetype<ECS_TYPE> archetype;
    protected int entitiesSize;
    protected Ref<ECS_TYPE>[] refs;           // Entity references
    protected Component<ECS_TYPE>[][] components;  // [componentIndex][entityIndex]

    /**
     * @return Archetype shared by all entities in this chunk
     */
    @Nonnull
    public Archetype<ECS_TYPE> getArchetype();

    /**
     * @return Number of entities in this chunk
     */
    public int size();

    /**
     * Convert to holder for serialization.
     * @return Holder containing chunk data
     */
    @Nonnull
    public Holder<ECS_TYPE> toHolder();
}

package com.hypixel.hytale.component;

import java.util.function.Supplier;
import javax.annotation.Nonnull;

/**
 * Central registry for components, resources, systems, and events.
 * Thread-safe with StampedLock for concurrent registration.
 */
public interface IComponentRegistry<ECS_TYPE> {

    // ===== COMPONENT REGISTRATION =====

    /**
     * Register component type with supplier.
     * @param clazz Component class
     * @param supplier Factory for creating instances
     * @return Component type handle
     */
    @Nonnull
    <T extends Component<ECS_TYPE>> ComponentType<ECS_TYPE, T>
        registerComponent(Class<? super T> clazz, Supplier<T> supplier);

    /**
     * Register component type with codec (for serialization).
     * @param clazz Component class
     * @param id Serialization ID
     * @param codec Serialization codec
     * @return Component type handle
     */
    @Nonnull
    <T extends Component<ECS_TYPE>> ComponentType<ECS_TYPE, T>
        registerComponent(Class<? super T> clazz, String id, BuilderCodec<T> codec);

    // ===== RESOURCE REGISTRATION =====

    /**
     * Register resource type with supplier.
     * @param clazz Resource class
     * @param supplier Factory for creating instances
     * @return Resource type handle
     */
    @Nonnull
    <T extends Resource<ECS_TYPE>> ResourceType<ECS_TYPE, T>
        registerResource(Class<? super T> clazz, Supplier<T> supplier);

    // ===== SYSTEM REGISTRATION =====

    /**
     * Register system type.
     * @param clazz System class
     * @return System type handle
     */
    @Nonnull
    <T extends ISystem<ECS_TYPE>> SystemType<ECS_TYPE, T>
        registerSystemType(Class<? super T> clazz);

    /**
     * Register system instance.
     * @param system System to register
     */
    void registerSystem(ISystem<ECS_TYPE> system);

    // ===== EVENT REGISTRATION =====

    /**
     * Register entity-targeted event type.
     * @param clazz Event class
     * @return Event type handle
     */
    @Nonnull
    <T extends EcsEvent> EntityEventType<ECS_TYPE, T>
        registerEntityEventType(Class<? super T> clazz);

    /**
     * Register world-wide event type.
     * @param clazz Event class
     * @return Event type handle
     */
    @Nonnull
    <T extends EcsEvent> WorldEventType<ECS_TYPE, T>
        registerWorldEventType(Class<? super T> clazz);

    // ===== SYSTEM GROUP REGISTRATION =====

    /**
     * Register system group for ordering.
     * @return System group handle
     */
    @Nonnull
    SystemGroup<ECS_TYPE> registerSystemGroup();

    // ===== SPATIAL REGISTRATION =====

    /**
     * Register spatial resource for spatial queries.
     * @param supplier Factory for spatial structure
     * @return Resource type handle
     */
    @Nonnull
    ResourceType<ECS_TYPE, SpatialResource<Ref<ECS_TYPE>, ECS_TYPE>>
        registerSpatialResource(Supplier<SpatialStructure<Ref<ECS_TYPE>>> supplier);
}

package com.hypixel.hytale.component.system;

import java.util.Set;
import javax.annotation.Nullable;

/**
 * Base interface for all ECS systems.
 */
public interface ISystem<ECS_TYPE> {
    /**
     * Called when system is registered.
     */
    default void onSystemRegistered() {}

    /**
     * Called when system is unregistered.
     */
    default void onSystemUnregistered() {}

    /**
     * @return System group for ordering, or null for default
     */
    @Nullable
    default SystemGroup<ECS_TYPE> getGroup() {
        return null;
    }

    /**
     * @return Dependencies for ordering
     */
    default Set<Dependency<ECS_TYPE>> getDependencies() {
        return Set.of();
    }

    /**
     * Calculate system execution order.
     * @param registry Component registry
     * @param systems Systems to order
     * @param systemSize Number of systems
     */
    static <ECS_TYPE> void calculateOrder(
        ComponentRegistry<ECS_TYPE> registry,
        ISystem<ECS_TYPE>[] systems,
        int systemSize);
}

package com.hypixel.hytale.component.system;

import java.util.function.Supplier;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;

/**
 * Base class for systems with component/resource registration helpers.
 */
public abstract class System<ECS_TYPE> implements ISystem<ECS_TYPE> {
    /**
     * Register component during system setup.
     * @param clazz Component class
     * @param id Serialization ID
     * @param codec Serialization codec
     * @param supplier Factory
     * @return Component type handle
     */
    protected <T extends Component<ECS_TYPE>> ComponentType<ECS_TYPE, T>
        registerComponent(
            Class<? super T> clazz,
            @Nullable String id,
            @Nullable BuilderCodec<T> codec,
            Supplier<T> supplier);

    /**
     * Register resource during system setup.
     */
    public <T extends Resource<ECS_TYPE>> ResourceType<ECS_TYPE, T>
        registerResource(
            Class<? super T> clazz,
            @Nullable String id,
            @Nullable BuilderCodec<T> codec,
            Supplier<T> supplier);
}

package com.hypixel.hytale.component.system;

/**
 * System that filters entities by query.
 */
public interface QuerySystem<ECS_TYPE> extends ISystem<ECS_TYPE> {
    /**
     * Test if archetype matches this system's query.
     * @param registry Component registry
     * @param archetype Archetype to test
     * @return true if archetype matches
     */
    default boolean test(ComponentRegistry<ECS_TYPE> registry, Archetype<ECS_TYPE> archetype) {
        return getQuery().test(archetype);
    }

    /**
     * @return Query defining which entities this system processes
     */
    @Nonnull
    Query<ECS_TYPE> getQuery();
}

package com.hypixel.hytale.component.system.tick;

/**
 * System that executes each tick.
 */
public abstract class TickingSystem<ECS_TYPE> extends System<ECS_TYPE>
    implements TickableSystem<ECS_TYPE> {

    /**
     * Called each tick.
     * @param dt Delta time since last tick
     * @param systemIndex This system's index
     * @param store Store to process
     */
    abstract void tick(float dt, int systemIndex, Store<ECS_TYPE> store);
}

/**
 * Ticking system that processes archetype chunks.
 */
public abstract class ArchetypeTickingSystem<ECS_TYPE> extends TickingSystem<ECS_TYPE>
    implements QuerySystem<ECS_TYPE> {

    /**
     * Process one archetype chunk.
     * @param dt Delta time
     * @param chunk Chunk to process
     * @param store Parent store
     * @param buffer Command buffer for deferred operations
     */
    abstract void tick(
        float dt,
        ArchetypeChunk<ECS_TYPE> chunk,
        Store<ECS_TYPE> store,
        CommandBuffer<ECS_TYPE> buffer);
}

/**
 * Ticking system with per-entity iteration and parallelization support.
 */
public abstract class EntityTickingSystem<ECS_TYPE>
    extends ArchetypeTickingSystem<ECS_TYPE> {

    /**
     * Process one entity.
     * @param dt Delta time
     * @param index Entity index in chunk
     * @param chunk Containing chunk
     * @param store Parent store
     * @param buffer Command buffer
     */
    abstract void tick(
        float dt,
        int index,
        ArchetypeChunk<ECS_TYPE> chunk,
        Store<ECS_TYPE> store,
        CommandBuffer<ECS_TYPE> buffer);

    /**
     * Helper for parallel entity processing.
     */
    static <ECS_TYPE> void doTick(
        EntityTickingSystem<ECS_TYPE> system,
        float dt,
        ArchetypeChunk<ECS_TYPE> chunk,
        Store<ECS_TYPE> store,
        CommandBuffer<ECS_TYPE> buffer);

    /**
     * Task data for parallel processing.
     */
    static class SystemTaskData<ECS_TYPE> implements IntConsumer {
        // Distributes work across parallel tasks
    }
}

package com.hypixel.hytale.component.system;

/**
 * System notified of entity lifecycle events.
 */
public abstract class RefSystem<ECS_TYPE> extends System<ECS_TYPE>
    implements QuerySystem<ECS_TYPE> {

    /**
     * Called when entity is added to store.
     * @param ref New entity reference
     * @param reason Why entity was added
     * @param store Parent store
     * @param buffer Command buffer
     */
    abstract void onEntityAdded(
        Ref<ECS_TYPE> ref,
        AddReason reason,
        Store<ECS_TYPE> store,
        CommandBuffer<ECS_TYPE> buffer);

    /**
     * Called when entity is being removed from store.
     * @param ref Entity being removed
     * @param reason Why entity is being removed
     * @param store Parent store
     * @param buffer Command buffer
     */
    abstract void onEntityRemove(
        Ref<ECS_TYPE> ref,
        RemoveReason reason,
        Store<ECS_TYPE> store,
        CommandBuffer<ECS_TYPE> buffer);
}

package com.hypixel.hytale.component.system;

/**
 * System notified of store lifecycle events.
 */
public abstract class StoreSystem<ECS_TYPE> extends System<ECS_TYPE> {
    /**
     * Called when system is added to store.
     * @param store Store this system was added to
     */
    abstract void onSystemAddedToStore(Store<ECS_TYPE> store);

    /**
     * Called when system is removed from store.
     * @param store Store this system was removed from
     */
    abstract void onSystemRemovedFromStore(Store<ECS_TYPE> store);
}

package com.hypixel.hytale.component.query;

import javax.annotation.Nonnull;

/**
 * Predicate for filtering entities by archetype.
 */
public interface Query<ECS_TYPE> {
    /**
     * Test if archetype matches this query.
     * @param archetype Archetype to test
     * @return true if matches
     */
    boolean test(Archetype<ECS_TYPE> archetype);

    /**
     * Check if query requires specific component.
     * @param type Component type to check
     * @return true if required
     */
    boolean requiresComponentType(ComponentType<ECS_TYPE, ?> type);

    /**
     * Validate query against registry.
     * @param registry Component registry
     */
    void validateRegistry(ComponentRegistry<ECS_TYPE> registry);

    /**
     * Validate query structure.
     */
    void validate();

    // ===== STATIC FACTORY METHODS =====

    /**
     * @return Query matching all archetypes
     */
    @Nonnull
    static <ECS_TYPE> AnyQuery<ECS_TYPE> any();

    /**
     * @return Query negating another query
     */
    @Nonnull
    static <ECS_TYPE> NotQuery<ECS_TYPE> not(Query<ECS_TYPE> query);

    /**
     * @return Query requiring all sub-queries to match
     */
    @Nonnull
    @SafeVarargs
    static <ECS_TYPE> AndQuery<ECS_TYPE> and(Query<ECS_TYPE>... queries);

    /**
     * @return Query requiring any sub-query to match
     */
    @Nonnull
    @SafeVarargs
    static <ECS_TYPE> OrQuery<ECS_TYPE> or(Query<ECS_TYPE>... queries);
}

package com.hypixel.hytale.component;

import java.util.Deque;
import java.util.function.Consumer;
import javax.annotation.Nonnull;

/**
 * Buffer for deferring entity operations.
 * Prevents concurrent modification during system iteration.
 */
public class CommandBuffer<ECS_TYPE> implements ComponentAccessor<ECS_TYPE> {
    private final Store<ECS_TYPE> store;
    private final Deque<Consumer<Store<ECS_TYPE>>> queue;
    private Ref<ECS_TYPE> trackedRef;
    private boolean trackedRefRemoved;
    private CommandBuffer<ECS_TYPE> parentBuffer;
    private Thread thread;

    /**
     * Queue operation for later execution.
     * @param consumer Operation to execute when buffer is flushed
     */
    void run(Consumer<Store<ECS_TYPE>> consumer);

    /**
     * Create nested command buffer.
     * @return Child command buffer
     */
    @Nonnull
    CommandBuffer<ECS_TYPE> fork();

    /**
     * Track if specific entity is removed.
     * @param ref Entity to track
     */
    void trackRef(Ref<ECS_TYPE> ref);

    /**
     * @return true if tracked entity was removed
     */
    boolean wasTrackedRefRemoved();

    // All ComponentAccessor methods are deferred to queue
    @Override
    public <T> T getComponent(Ref<ECS_TYPE> ref, ComponentType<ECS_TYPE, T> type) {
        // Deferred execution
    }
}

// During system tick, use command buffer for safe modifications
@Override
public void tick(float dt, int index, ArchetypeChunk<ChunkStore> chunk,
                Store<ChunkStore> store, CommandBuffer<ChunkStore> buffer) {

    Ref<ChunkStore> ref = chunk.refs[index];
    MyComponent comp = store.getComponent(ref, MY_COMPONENT_TYPE);

    if (shouldRemoveEntity(comp)) {
        // Don't modify directly - defer via buffer
        buffer.run(s -> s.removeEntity(ref, RemoveReason.LOGIC));
    }

    if (shouldAddComponent(comp)) {
        // Defer component addition
        buffer.addComponent(ref, OTHER_COMPONENT_TYPE, new OtherComponent());
    }
}

package com.hypixel.hytale.component.dependency;

/**
 * Declares ordering between systems.
 */
public abstract class Dependency<ECS_TYPE> {
    protected final Order order;      // BEFORE or AFTER
    protected final int priority;     // Ordering within same relationship

    /**
     * Validate dependency against registry.
     */
    abstract void validate(ComponentRegistry<ECS_TYPE> registry);

    /**
     * Add edge to dependency graph.
     */
    abstract void resolveGraphEdge(
        ComponentRegistry<ECS_TYPE> registry,
        ISystem<ECS_TYPE> system,
        DependencyGraph<ECS_TYPE> graph);
}

/**
 * Dependency on another system type.
 */
public class SystemDependency<ECS_TYPE, T extends ISystem<ECS_TYPE>>
    extends Dependency<ECS_TYPE> {

    private final Class<T> systemClass;

    public SystemDependency(Order order, Class<T> systemClass);
    public SystemDependency(Order order, Class<T> systemClass, int priority);
    public SystemDependency(Order order, Class<T> systemClass, OrderPriority priority);
}

/**
 * Ordering enum.
 */
public enum Order {
    BEFORE,  // This system runs before dependency
    AFTER    // This system runs after dependency
}

public class MySystem extends EntityTickingSystem<ChunkStore> {
    @Override
    public Set<Dependency<ChunkStore>> getDependencies() {
        return Set.of(
            // Run after PhysicsSystem
            new SystemDependency<>(Order.AFTER, PhysicsSystem.class),
            // Run before RenderingSystem
            new SystemDependency<>(Order.BEFORE, RenderingSystem.class)
        );
    }
}

package com.hypixel.hytale.component.system;

/**
 * Base class for all ECS events.
 */
public abstract class EcsEvent {}

/**
 * Event targeted at specific entities.
 */
public class EntityEventType<ECS_TYPE, Event extends EcsEvent> {
    // Type handle for entity events
}

/**
 * Event broadcast to all listeners.
 */
public class WorldEventType<ECS_TYPE, Event extends EcsEvent> {
    // Type handle for world events
}

/**
 * Cancellable ECS event.
 */
public interface ICancellableEcsEvent {
    boolean isCancelled();
    void setCancelled(boolean cancelled);
}

// Define custom event
public class DamageEvent extends EcsEvent implements ICancellableEcsEvent {
    private final float damage;
    private final DamageCause cause;
    private boolean cancelled = false;

    public DamageEvent(float damage, DamageCause cause) {
        this.damage = damage;
        this.cause = cause;
    }

    public float getDamage() { return damage; }
    public DamageCause getCause() { return cause; }

    @Override
    public boolean isCancelled() { return cancelled; }
    @Override
    public void setCancelled(boolean cancelled) { this.cancelled = cancelled; }
}

// Register event type
EntityEventType<EntityStore, DamageEvent> DAMAGE_EVENT =
    registry.registerEntityEventType(DamageEvent.class);

// Invoke event
DamageEvent event = new DamageEvent(10.0f, DamageCause.FALL);
store.invoke(DAMAGE_EVENT, entityRef, event);

if (!event.isCancelled()) {
    // Apply damage
}