Instalación y Configuración¶

Esta guía te llevará paso a paso por el proceso de configurar tu entorno de desarrollo para crear plugins de Hytale.

1. Configurar el Proyecto¶

Opción A: Con IntelliJ IDEA¶

Crear Nuevo Proyecto
Abre IntelliJ IDEA
File → New → Project
Selecciona Java (o Gradle/Maven)
JDK: Selecciona JDK 17+
Click Create

Configurar Estructura

mi-plugin/
├── src/
│   └── main/
│       ├── java/
│       │   └── com/ejemplo/miplugin/
│       └── resources/
│           └── META-INF/
│               └── services/
├── libs/
│   └── hytale-api.jar
└── build.gradle

Agregar Dependencias

Si usas Gradle, edita build.gradle:

plugins {
    id 'java'
}

group = 'com.ejemplo.miplugin'
version = '1.0.0-SNAPSHOT'

sourceCompatibility = '17'
targetCompatibility = '17'

repositories {
    mavenCentral()
}

dependencies {
    // API de Hytale
    compileOnly files('libs/hytale-api.jar')

    // Para manipulación de bytecode
    implementation 'org.ow2.asm:asm:9.6'
    implementation 'org.ow2.asm:asm-commons:9.6'
    implementation 'org.ow2.asm:asm-util:9.6'

    // FastUtil (usado por Hytale)
    implementation 'it.unimi.dsi:fastutil:8.5.12'
}

jar {
    manifest {
        attributes(
            'Implementation-Title': project.name,
            'Implementation-Version': project.version
        )
    }
}

Opción B: Con Maven¶

Crea pom.xml:

href="#__codelineno-2-1"><?xml version="1.0" encoding="UTF-8"?> ;project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <groupId>com.ejemplo</groupId> <artifactId>mi-plugin</artifactId> <version>1.0.0-SNAPSHOT</version> <properties> <maven.compiler.source>17</maven.compiler.source> <maven.compiler.target>17</maven.compiler.target> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> </properties> <dependencies> <dependency> <groupId>org.ow2.asm</groupId> <artifactId>asm</artifactId> <version>9.6</version> </dependency> <dependency> <groupId>it.unimi.dsi</groupId> <artifactId>fastutil</artifactId> <version>8.5.12</version> </dependency> </dependencies> ></project>

2. Extraer la API de Hytale¶

Para desarrollar plugins, necesitas la API de Hytale. Si ya tienes el código descompilado:

Opción 1: Usar JAR Directamente¶

Coloca el JAR descompilado en libs/hytale-api.jar

Opción 2: Crear JAR de API¶

Si tienes el código fuente:

# Compilar el código descompilado
javac -d build/classes com/hypixel/hytale/**/*.java

# Crear JAR
cd build/classes
jar cf ../../libs/hytale-api.jar .

3. Configurar Early Plugin¶

Para crear un Early Plugin que transforme clases:

3.1 Crear ClassTransformer¶

package com.ejemplo.miplugin;

import com.hypixel.hytale.plugin.early.ClassTransformer;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;

public class MiTransformador implements ClassTransformer {

    @Override
    public int priority() {
        return 100; // Mayor = se ejecuta primero
    }

    @Override
    @Nullable
    public byte[] transform(@Nonnull String className,
                           @Nonnull String classPath,
                           @Nonnull byte[] bytecode) {
        // Aquí va tu lógica de transformación
        if (className.equals("com.hypixel.hytale.AlgunaClase")) {
            return transformarClase(bytecode);
        }
        return null; // No modificar esta clase
    }

    private byte[] transformarClase(byte[] bytecode) {
        // Usar ASM para transformar
        return bytecode; // placeholder
    }
}

3.2 Registrar con Service Loader¶

Crea el archivo src/main/resources/META-INF/services/com.hypixel.hytale.plugin.early.ClassTransformer:

com.ejemplo.miplugin.MiTransformador

3.3 Compilar¶

# Con Gradle
./gradlew build

# Con Maven
mvn package

El JAR resultante estará en: - Gradle: build/libs/mi-plugin-1.0.0-SNAPSHOT.jar - Maven: target/mi-plugin-1.0.0-SNAPSHOT.jar

4. Instalar en el Servidor¶

4.1 Ubicar el Plugin¶

Para Early Plugin:

cp mi-plugin-1.0.0-SNAPSHOT.jar /ruta/servidor/earlyplugins/

4.2 Ejecutar el Servidor¶

java -jar hytale-server.jar --accept-early-plugins

Confirmación Requerida

Si no usas --accept-early-plugins, el servidor pedirá confirmación interactiva al detectar transformadores.

4.3 Verificar Carga¶

Deberías ver en los logs:

[EarlyPlugin] Found: mi-plugin-1.0.0-SNAPSHOT.jar
[EarlyPlugin] Loading transformer: com.ejemplo.miplugin.MiTransformador (priority=100)
===============================================================================================
                              Loaded 1 class transformer(s)!!
===============================================================================================

5. Configurar Debugging¶

En IntelliJ IDEA¶

Crear Configuración de Debug
Run → Edit Configurations
Click + → JAR Application
Path to JAR: Selecciona hytale-server.jar
VM options: -Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=5005
Program arguments: --accept-early-plugins
Working directory: Directorio del servidor
Conectar Debugger
Coloca breakpoints en tu código
Click en el botón de Debug
El servidor se ejecutará y podrás depurar

Con Debug Remoto¶

Si el servidor ya está ejecutándose:

java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005 \
     -jar hytale-server.jar --accept-early-plugins

Luego en IntelliJ: - Run → Edit Configurations → + → Remote JVM Debug - Host: localhost - Port: 5005 - Click Debug

6. Verificar Instalación¶

Crea un test simple:

package com.ejemplo.miplugin;

import com.hypixel.hytale.plugin.early.ClassTransformer;

public class TestTransformer implements ClassTransformer {
    @Override
    public byte[] transform(String className, String classPath, byte[] bytecode) {
        System.out.println("[MiPlugin] Transformando: " + className);
        return null;
    }
}

Si ves los mensajes en la consola, ¡tu plugin está funcionando!

Solución de Problemas¶

El plugin no se carga¶

✅ Verifica que el JAR esté en earlyplugins/
✅ Confirma que el archivo de Service Loader existe
✅ Revisa que el nombre de la clase sea correcto

Errores de compilación¶

✅ Verifica la versión de Java (debe ser 17+)
✅ Asegúrate de tener hytale-api.jar en libs/
✅ Refresca las dependencias de Gradle/Maven

Servidor no inicia¶

✅ Revisa los logs para errores
✅ Asegúrate de usar --accept-early-plugins
✅ Verifica que tu transformador no lance excepciones

Próximos Pasos¶

Ahora que tienes tu entorno configurado:

Arquitectura de Hytale: Entiende la estructura interna
Tutorial: Hello World: Crea tu primer plugin funcional
API Reference: Explora la API en detalle

¿Problemas? Consulta Troubleshooting