Introducción al Desarrollo de Mods para Hytale¶
Bienvenido a la guía completa de desarrollo de mods para Hytale. Esta guía te introducirá al mundo del modding, explicando qué son los mods, qué puedes hacer con ellos, y cómo empezar.
¿Qué es un Mod?¶
Un mod (modificación) es un paquete que extiende y modifica Hytale, agregando contenido personalizado como:
- Bloques y items nuevos
- Entidades y criaturas
- Mecánicas de juego
- Sistemas completos
- Assets visuales y sonoros
Mods vs Plugins¶
Plugins¶
Los plugins modifican el código del servidor en tiempo de ejecución usando transformación de bytecode.
Características: - Se cargan antes del servidor (early plugins) - Pueden modificar cualquier clase del juego - Útiles para cambiar comportamiento existente - No requieren assets adicionales - Principalmente código Java
Ejemplo de uso:
// Plugin que modifica comportamiento existente
public class DamageMultiplierPlugin implements ClassTransformer {
@Override
public byte[] transform(String className, String classPath, byte[] bytecode) {
// Modificar método takeDamage() para multiplicar daño x2
return transformedBytecode;
}
}
Mods¶
Los mods combinan plugins con contenido personalizado (assets, configuraciones JSON, etc.).
Características: - Incluyen early plugins para lógica custom - Definen bloques, items, entidades nuevos - Incluyen assets (modelos, texturas, sonidos) - Configuraciones JSON para contenido - Sistema completo de modding
Ejemplo de estructura:
mi-mod/
├── earlyplugin/
│ └── MiModPlugin.jar # Early plugin con lógica
├── assets/
│ ├── blocks/
│ │ └── custom_block.json # Definición de bloque
│ ├── items/
│ │ └── custom_item.json # Definición de item
│ └── models/
│ └── custom_block.vox # Modelo 3D
└── mod.json # Metadata del mod
¿Cuándo Usar Cada Uno?¶
| Necesitas... | Usa |
|---|---|
| Cambiar comportamiento existente | Plugin |
| Agregar nuevos bloques/items | Mod |
| Modificar mecánicas del juego | Plugin |
| Crear nuevas criaturas | Mod |
| Sistema complejo con assets | Mod |
| Hook simple sin assets | Plugin |
Recomendación: La mayoría de modificaciones complejas usan ambos - un early plugin para la lógica y un mod para el contenido.
¿Qué Puedes Hacer con Mods?¶
1. Bloques Personalizados¶
Crear bloques completamente nuevos con propiedades custom.
{
"id": "mymod:custom_ore",
"name": "Custom Ore",
"hardness": 3.5,
"model": "mymod:models/custom_ore",
"drops": [
{
"item": "mymod:custom_gem",
"count": {"min": 1, "max": 3}
}
],
"interactions": {
"Mine": "mymod:mine_custom_ore"
}
}
2. Items Personalizados¶
Items con funcionalidad única.
{
"id": "mymod:magic_staff",
"name": "Magic Staff",
"type": "Tool",
"maxStackSize": 1,
"durability": 500,
"interactions": {
"RightClick": "mymod:cast_spell",
"LeftClick": "mymod:melee_attack"
},
"model": "mymod:models/magic_staff"
}
3. Entidades y Criaturas¶
NPCs, enemigos, y criaturas personalizadas.
{
"id": "mymod:custom_npc",
"name": "Village Elder",
"type": "NPC",
"health": 100,
"ai": "mymod:npc_ai",
"interactions": {
"Talk": "mymod:npc_dialogue",
"Trade": "mymod:npc_trading"
},
"model": "mymod:models/village_elder"
}
4. Sistemas de Juego Completos¶
Combinar plugins y assets para crear sistemas complejos.
Ejemplo: Sistema de Magia
graph TD
A[Sistema de Magia] --> B[Early Plugin]
A --> C[Assets]
B --> D[Spell Registry]
B --> E[Mana System]
B --> F[Casting Logic]
C --> G[Spell Items]
C --> H[Particle Effects]
C --> I[Sound Effects]5. Mecánicas Avanzadas¶
- Sistemas de crafteo personalizados
- Quest systems
- Economía y comercio
- Facciones y guilds
- Skills y progresión
- Minijuegos
Arquitectura de un Mod¶
Un mod bien estructurado sigue esta arquitectura:
graph LR
A[Mod Package] --> B[Early Plugin]
A --> C[Assets]
A --> D[Configurations]
B --> E[Core Logic]
B --> F[Registries]
B --> G[Event Handlers]
C --> H[Models]
C --> I[Textures]
C --> J[Sounds]
D --> K[JSON Configs]
D --> L[Data Files]Componentes Principales¶
1. Early Plugin¶
Código Java que se ejecuta antes del servidor.
package com.ejemplo.mimod;
import com.hypixel.hytale.plugin.early.ClassTransformer;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
public class MiModPlugin implements ClassTransformer {
@Override
public int priority() {
return 100;
}
@Override
@Nullable
public byte[] transform(@Nonnull String className,
@Nonnull String classPath,
@Nonnull byte[] bytecode) {
// Inicializar mod al transformar HytaleServer
if (className.equals("com.hypixel.hytale.server.core.HytaleServer")) {
return injectModInitialization(bytecode);
}
return null;
}
private byte[] injectModInitialization(byte[] bytecode) {
// Inyectar llamada a: MiMod.initialize()
// Esto registrará bloques, items, etc.
return transformedBytecode;
}
}
2. Mod Registry¶
Sistema central que registra todo el contenido del mod.
package com.ejemplo.mimod;
import com.hypixel.hytale.server.core.modules.interaction.interaction.config.Interaction;
import java.util.List;
public class MiMod {
public static final String MOD_ID = "mymod";
public static final String MOD_NAME = "Mi Mod Increíble";
public static final String VERSION = "1.0.0";
/**
* Inicializa el mod.
* Llamado desde el early plugin.
*/
public static void initialize() {
System.out.println("[" + MOD_NAME + "] Initializing v" + VERSION);
// Registrar interacciones
registerInteractions();
// Registrar bloques
registerBlocks();
// Registrar items
registerItems();
System.out.println("[" + MOD_NAME + "] Initialized successfully!");
}
private static void registerInteractions() {
var store = Interaction.getAssetStore();
store.loadAssets(MOD_ID + ":" + MOD_ID, List.of(
new CastSpellInteraction(),
new MineCustomOreInteraction(),
new NPCDialogueInteraction()
));
}
private static void registerBlocks() {
// Registrar bloques custom
// Los JSONs en assets/ se cargarán automáticamente
}
private static void registerItems() {
// Registrar items custom
// Los JSONs en assets/ se cargarán automáticamente
}
}
3. Assets¶
Archivos de configuración y recursos.
Estructura de assets:
assets/
├── blocks/
│ ├── custom_ore.json
│ └── magic_block.json
├── items/
│ ├── magic_staff.json
│ └── custom_gem.json
├── entities/
│ └── custom_npc.json
├── interactions/
│ ├── cast_spell.json
│ └── mine_custom_ore.json
├── models/
│ ├── custom_ore.vox
│ ├── magic_staff.vox
│ └── custom_npc.vox
├── textures/
│ ├── custom_ore.png
│ └── magic_staff.png
└── sounds/
├── spell_cast.ogg
└── ore_break.ogg
Herramientas Necesarias¶
1. Desarrollo de Código¶
- JDK 17+: Para compilar código Java
- IntelliJ IDEA o Eclipse: IDE para desarrollo
- Gradle o Maven: Build tools
- Git: Control de versiones
2. Creación de Assets¶
- MagicaVoxel: Editor de modelos voxel
- GIMP o Photoshop: Edición de texturas
- Audacity: Edición de sonidos
- Blender: Modelado 3D avanzado (opcional)
3. Testing¶
- Servidor de Hytale: Para probar tu mod
- Debugger: Para debugging
- Profiler: Para optimización
Primeros Pasos¶
1. Configurar Entorno de Desarrollo¶
# Crear directorio del proyecto
mkdir mi-primer-mod
cd mi-primer-mod
# Inicializar Git
git init
# Crear estructura básica
mkdir -p src/main/java/com/ejemplo/mimod
mkdir -p src/main/resources/META-INF/services
mkdir -p assets/{blocks,items,models,textures,sounds}
2. Crear build.gradle¶
plugins {
id 'java'
}
group = 'com.ejemplo.mimod'
version = '1.0.0'
sourceCompatibility = '17'
targetCompatibility = '17'
repositories {
mavenCentral()
}
dependencies {
// Hytale API
compileOnly files('libs/hytale-api.jar')
// ASM para transformación
implementation 'org.ow2.asm:asm:9.6'
implementation 'org.ow2.asm:asm-commons:9.6'
// FastUtil
compileOnly 'it.unimi.dsi:fastutil:8.5.12'
// Testing
testImplementation 'org.junit.jupiter:junit-jupiter:5.9.3'
}
jar {
archiveFileName = "${project.name}-${project.version}.jar"
manifest {
attributes(
'Implementation-Title': project.name,
'Implementation-Version': project.version
)
}
// Incluir dependencias
from {
configurations.runtimeClasspath.collect {
it.isDirectory() ? it : zipTree(it)
}
}
duplicatesStrategy = DuplicatesStrategy.EXCLUDE
}
tasks.named('test') {
useJUnitPlatform()
}
3. Crear mod.json¶
{
"id": "mymod",
"name": "Mi Primer Mod",
"version": "1.0.0",
"description": "Un mod de ejemplo para Hytale",
"authors": ["Tu Nombre"],
"website": "https://ejemplo.com/mymod",
"license": "MIT",
"dependencies": {
"hytale": ">=1.0.0"
},
"earlyPlugin": {
"main": "com.ejemplo.mimod.MiModPlugin",
"priority": 100
},
"assets": {
"blocks": "assets/blocks",
"items": "assets/items",
"entities": "assets/entities",
"interactions": "assets/interactions",
"models": "assets/models",
"textures": "assets/textures",
"sounds": "assets/sounds"
}
}
4. Estructura Completa del Proyecto¶
mi-primer-mod/
├── src/
│ └── main/
│ ├── java/
│ │ └── com/
│ │ └── ejemplo/
│ │ └── mimod/
│ │ ├── MiModPlugin.java
│ │ ├── MiMod.java
│ │ ├── interactions/
│ │ │ ├── CastSpellInteraction.java
│ │ │ └── MineCustomOreInteraction.java
│ │ └── util/
│ │ └── ModHelper.java
│ └── resources/
│ └── META-INF/
│ └── services/
│ └── com.hypixel.hytale.plugin.early.ClassTransformer
├── assets/
│ ├── blocks/
│ ├── items/
│ ├── models/
│ └── textures/
├── build.gradle
├── settings.gradle
├── mod.json
├── README.md
└── LICENSE
Flujo de Trabajo de Desarrollo¶
graph TD
A[Idea de Mod] --> B[Diseñar Contenido]
B --> C[Crear Assets]
B --> D[Escribir Código]
C --> E[Configurar JSONs]
D --> F[Implementar Lógica]
E --> G[Compilar Mod]
F --> G
G --> H[Probar en Servidor]
H --> I{¿Funciona?}
I -->|No| J[Debug]
J --> D
I -->|Sí| K[Optimizar]
K --> L[Documentar]
L --> M[Publicar]Conceptos Clave¶
1. Mod ID¶
Identificador único de tu mod. Debe ser: - Minúsculas - Sin espacios - Alfanumérico (y guiones bajos) - Único en el ecosistema de mods
2. Namespacing¶
Todos los recursos usan el patrón modid:resource:
{
"id": "mymod:custom_block",
"texture": "mymod:textures/custom_block",
"model": "mymod:models/custom_block"
}
3. Asset Loading¶
Hytale carga assets automáticamente desde directorios especificados en mod.json.
4. Registro de Contenido¶
Todo contenido custom debe registrarse en el AssetStore apropiado:
// Registrar interacciones
Interaction.getAssetStore().loadAssets("mymod:mymod", interactions);
// Registrar bloques
Block.getAssetStore().loadAssets("mymod:mymod", blocks);
// Registrar items
Item.getAssetStore().loadAssets("mymod:mymod", items);
Ejemplos de Mods¶
Mod Simple: Custom Block¶
Un mod básico que agrega un bloque personalizado.
Contenido: - 1 bloque custom - 1 interacción de minado - Textura y modelo
Mod Intermedio: Magic System¶
Un sistema de magia con: - Items mágicos (staffs, wands) - Interacciones de casting - Partículas y efectos - Sistema de mana
Mod Avanzado: RPG Extension¶
Un mod completo de RPG con: - Sistema de clases - Skills y habilidades - Quest system - NPCs y diálogos - Economía - Dungeons
Próximos Pasos¶
Ahora que entiendes los conceptos básicos, continúa con:
- Creating a Mod: Tutorial paso a paso para crear tu primer mod completo
- Interaction System: Aprende a crear interacciones personalizadas
- Meta System Usage: Usa el sistema de metadata para datos persistentes
Recursos Adicionales¶
- Plugin Guide: Crear early plugins
- API Reference: Documentación completa de la API
- Examples: Ejemplos de código
- Community Mods: Inspiración y recursos
¿Listo para empezar? Continúa con Creating a Mod