Tutorial de creación de MODs y API Lua

1. Inicio rápido

1.1 ¿Qué es un MOD?

Un MOD es un paquete de contenido creado por jugadores que modifica las estadísticas, habilidades, skins y propiedades de hitbox de las criaturas. El juego incluye dos MODs de ejemplo — DemoCharacterMod y DemoSkinsMod — ubicados en el directorio de MODs del juego (ver ruta arriba). Puedes copiarlos y modificarlos directamente para empezar rápidamente.

1.2 Ubicación del directorio de MODs

1.3 Estructura del directorio de MODs

Mods/
├── DemoCharacterMod/           ← Ejemplo completo (estadísticas+habilidades+hitbox+skin)
│   ├── mod.json                ← Manifiesto del MOD
│   ├── preview.jpg             ← Imagen de vista previa
│   ├── CharacterAsset/
│   │   └── allo.txt            ← Configuración del Alosaurio (los 4 tipos)
│   └── SkinsAsset/
│       └── Crooked mouth.png   ← Textura de skin
│
├── DemoSkinsMod/               ← Ejemplo de MOD solo de skins
│   ├── mod.json
│   ├── preview.jpg
│   └── SkinsAsset/
│       ├── allo_deser_allo.txt ← Script de skin
│       └── deser_allo.png      ← Textura de skin
│
└── MyFirstMod/                 ← Directorio raíz de tu MOD
    ├── mod.json
    └── CharacterAsset/
        └── allo.txt

1.4 Crear mod.json

{
  "Name": "MyFirstMod",
  "Author": "Tu nombre",
  "Version": "1.0",
  "SupportedVersion": "0.6.*",
  "Priority": 0,
  "Description": "Mi primer MOD",
  "PreviewImagePath": "preview.jpg",
  "Tags": "Character"
}

1.5 La interfaz de MODs en el juego de un vistazo

En la pantalla de inicio, haz clic en Gestión de MODs para abrir la interfaz de MODs. Tiene tres pestañas — MODs locales, Workshop, Administrar MODs — más los botones Crear MOD y Establecer directorio, que cubren todo el recorrido del autor, de la creación a la prueba.

1.6 Crea tu MOD (recomendado para principiantes)

El juego incluye una herramienta de creación de MODs — sin crear carpetas a mano:
① Inicia sesión (crear un MOD requiere iniciar sesión; el MOD queda vinculado a tu cuenta).
② Gestión de MODs → clic en Crear MOD.
③ Rellena el nombre (solo letras/números/guión bajo/guión, 1–64 caracteres), autor, versión, versión soportada, descripción, etiquetas, y elige una plantilla.
④ Haz clic en Crear — el sistema genera la estructura del directorio (mod.json más la carpeta de script de ejemplo de la plantilla).
⑤ El MOD aparece entonces en la pestaña Administrar MODs como borrador, aún no en la lista de carga local.

1.7 Editar y previsualizar

① Encuentra tu MOD en Administrar MODs. Si usaste «Establecer directorio», el MOD se sincroniza a esa carpeta externa y puedes abrirlo directo en un editor de texto; si no, edita los scripts Lua (CharacterAsset/*.txt, etc.), PNGs de skin y el preview.jpg dentro de su carpeta en el directorio de MODs del juego.
② Usa el botón Editar de la fila para cambiar versión, versión soportada, descripción y etiquetas (el nombre queda bloqueado).
③ Al terminar, haz clic en Previsualizar para enviar el borrador a la lista de carga de MODs locales.

1.8 Probar en el juego (ciclo de desarrollo del autor)

1. Crear: Gestión de MODs → Crear MOD → elige una plantilla → Crear (genera un borrador; ver 1.6).
2. Editar: edita los scripts y metadatos en Administrar MODs (ver 1.7).
3. Previsualizar: haz clic en Previsualizar para mover el borrador a la lista de carga de MODs locales.
4. Habilitar: cambia a MODs locales, confirma que el estado es «Habilitado» (verde) y «Versión soportada» está en verde (rojo significa incompatible con la versión actual del juego — corrige SupportedVersion).
5. Probar: entra en un solo jugador o crea una sala — los atributos/habilidades/skins modificados surten efecto de inmediato.
6. Iterar: vuelve a Administrar MODs y edita los scripts → crea una sala Host local para actualizar la instantánea de vista previa con el borrador más reciente → vuelve a entrar en la partida para verificar. Después de activar la vista previa sincronizada una vez, no hace falta reiniciar el juego ni volver a activarla.
7. Distribuir: cuando estés satisfecho, usa Exportar para generar un archivo .mod y compartirlo; en Steam también puedes Subir a Workshop para publicarlo.

1.9 Modo de vista previa sincronizada (pruebas de desarrollo)

Vista previa sincronizada en Administrar MODs crea una instantánea de ejecución independiente del borrador y la registra en la lista de carga local. El código fuente del autor permanece en el directorio de Administrar MODs; la vista previa sincronizada no publica ni sube el MOD a Workshop.

1.10 Exportar .mod (compartir e instalar)

Exportar empaqueta la copia de trabajo actual de Administrar MODs en un archivo comprimido .mod y abre el selector de ubicación de guardado del sistema. La raíz del paquete es el directorio que contiene mod.json e incluye scripts, imágenes y demás archivos del MOD. Exportar no activa la vista previa, no modifica el borrador, no hace público el MOD ni lo sube a Workshop.

1. Autor: en Administrar MODs, pulsa Exportar, guarda el archivo .mod con el selector del sistema y envíalo a probadores o jugadores.
2. Destinatario: en la pestaña MODs locales, pulsa Importar MOD, selecciona el .mod recibido (o un .zip compatible) y confirma que aparece y está activado en la lista de carga local.
3. Multijugador: antes de entrar o crear una sala con MOD, todos los participantes deben usar el mismo contenido, versión y estado de activación del MOD. Un paquete exportado no sustituye la publicación en Workshop.

2. MOD de estadísticas de personaje

Crea un archivo .txt en el directorio CharacterAsset/ y define una tabla CharacterAsset para modificar los atributos de las criaturas del juego. Los campos no rellenados conservan los valores originales. A continuación se muestra la configuración completa de allo.txt del DemoCharacterMod incluido en el juego, mostrando todos los campos modificables.

2.1 Ejemplo completo (allo.txt de DemoCharacterMod)

-- Modificar los atributos completos del Alosaurio (*no eliminar los siguientes elementos)
CharacterAsset = {
    name    = "Alosaurio",       -- Nombre del personaje
    enable  = true,              -- Si habilitar el personaje
    jump    = false,             -- Si permitir salto (necesita animación correspondiente)
    race    = "allo",            -- Etiqueta de raza (*obligatorio, clave única de coincidencia)
    ropoda  = 0,                 -- Tipo de nido (-1=ninguno, 0=terópodo, 1=saurópodo, 2=ornitisquio)
    ropode  = 0,                 -- Tipo de huevo (-1=ninguno, 0=terópodo, 1=saurópodo, 2=ornitisquio)
    volume  = 2,                 -- Clase de tamaño 0~5 (ligero→súper)
    rank    = 7,                 -- Estrellas 0~12 (nivel S1~SS)
    branch  = 3,                 -- Clasificación de familia 0~25
    habit   = 0,                 -- Hábito (0=terrestre, 1=hidrófilo, 2=reptil marino, 3=acuático, 4=anfibio, 5=volador)
    type    = 0,                 -- Categoría (0=carnívoro, 1=herbívoro, 2=acuático, 3=artrópodo, 4=mamífero, 5=volador)
    taste   = 0,                 -- Dieta (0=carnívoro, 1=flores, 2=hojas, 3=omnívoro)
    spawn   = 0,                 -- Reproducción (0=ovíparo, 1=vivíparo)
    health  = 26503.0,           -- Puntos de vida
    hunger  = 12227.0,           -- Hambre
    water   = 3128.0,            -- Agua
    oxygen  = 474.0,             -- Oxígeno
    stamina = 100.0,             -- Aguante
    attack  = 2802.0,            -- Ataque
    defend  = 779.0,             -- Defensa
    pen     = 5,                 -- Nivel de penetración 0~10
    ten     = 3,                 -- Nivel de tenacidad 0~10
    restore = 266.0,             -- Capacidad de recuperación
    consume = 100.0,             -- Consumo de crucero
    weight  = 3600.0,            -- Peso (kg)
    speed   = 27.01,             -- Velocidad al caminar (km/h)
    swim    = 13.5,              -- Velocidad al nadar (km/h)
    flying  = 0.0,               -- Velocidad de vuelo (km/h)
    runSpeed    = 54.01,         -- Velocidad al correr (km/h)
    turnSpeed   = 0.61,          -- Agilidad de giro (grados/s)
    growtime    = 1560.0,        -- Tiempo para alcanzar adulto (segundos)
    ovumtime    = 1080.0,        -- Intervalo de formación de huevos (segundos)
    hatching    = 2210.0,        -- Tiempo de incubación (segundos)
    safe        = 1800.0,        -- Periodo de protección juvenil (segundos)
    skill   = "LifeDrain,3;",    -- Habilidad EX innata
    gene    = "",                -- Gen innato
}

2.2 Clasificación e identidad

2.3 Supervivencia y combate

2.4 Velocidad de movimiento (km/h)

2.5 Parámetros de tiempo

2.6 Eficiencia de órganos (0.0 ~ 1.0)

2.7 Dimensiones corporales y rasgos innatos

3. MOD de habilidades

Usa la tabla CharacterSkill para modificar los ataques de los personajes. Cada habilidad se define como par clave-valor (la clave puede nombrarse libremente). Se puede combinar con CharacterAsset en el mismo archivo .txt.

3.1 Ejemplo completo (de DemoCharacterMod)

CharacterSkill = {
    attack1 = {
        Race         = "allo",      -- *Obligatorio* etiqueta de raza
        AttackOrder  = 1,           -- Índice de ataque (1=boca1, 2=boca2...)
        AttackType   = 0,           -- Tipo de ataque 0~7 (ver enumeración abajo)
        DamageMode   = 0,           -- Tipo de daño 0~2 (ver enumeración abajo)
        Area         = nil,         -- Zona permitida nil=sin límite, {0,1}=solo tierra+agua somera
        AttackRange  = 1.0,         -- Radio de colisión de ataque (m)
        Modify       = 2.0,         -- Coeficiente de daño (1=sin modificación)
        UseStamina   = 0.01,        -- Porcentaje de aguante consumido (0=por defecto del sistema)
        TriggerSkill = "Scars,2;",  -- Habilidad activada al impactar (formato: "Nombre,Nivel;")
    },
    attack2 = {
        Race         = "allo",
        AttackOrder  = 2,
        AttackType   = 1,           -- Cola
        DamageMode   = 1,           -- Daño en área AOE
        AttackRange  = 3.0,
        Modify       = 0.8,
        UseStamina   = 0.03,
        TriggerSkill = "Blood,2;",
    },
}

3.2 Enumeración de AttackType (tipo de ataque)

3.3 Enumeración de DamageMode (tipo de daño)

3.4 Enumeración de Area (zona disponible)

4. MOD de hitbox (zonas de impacto)

Usa la tabla CharacterHitGroup para modificar la tasa de penetración de armadura y el multiplicador de daño de cada parte del cuerpo del personaje, creando puntos débiles o blindaje reforzado.

4.1 Constantes de partes del cuerpo

4.2 Ejemplo (de DemoCharacterMod)

CharacterHitGroup = {
    head = {
        Race              = "allo",
        PartType          = BODY_HEAD,
        PenetrationRate   = 0.6,    -- Tasa de penetración 0~1 (mayor = más fácil de penetrar)
        DamageMultiplier  = 1.5,    -- Multiplicador de daño 0.5~2 (>1 = más daño recibido)
    },
    body = {
        Race              = "allo",
        PartType          = BODY_BODY,
        PenetrationRate   = 0.05,   -- Casi impenetrable
        DamageMultiplier  = 0.8,    -- 20% de reducción de daño
    },
    belly = {
        Race              = "allo",
        PartType          = BODY_BELLY,   -- Vientre (valor=7)
        PenetrationRate   = 0.9,    -- Penetración muy alta
        DamageMultiplier  = 1.8,    -- Gran aumento de daño recibido
    },
}

5. MOD de gen BUFF

El MOD de gen BUFF sobrescribe los valores y la configuración de genes/habilidades/BUFFs existentes mediante la tabla global CharacterGeneBuff. Al igual que CharacterAsset, el script es XLua (.txt) y puede estar en el mismo archivo o en una subcarpeta GeneBuff/ dedicada.

5.1 Estructura de configuración (CharacterGeneBuff)

CharacterGeneBuff = {
    -- Clave = la etiqueta del gen existente a sobrescribir (obtén las TAG en la página lista de habilidades y genes)
    Bleed = {
        Repeat  = "COVER",   -- Opcional: regla de sobrescritura
        Upgrade = "EXP",     -- Opcional: modo de mejora
        With    = "",        -- Opcional: DSL de efecto adjunto, formato tag,nivel;
        Copes   = "",        -- Opcional: etiqueta del objetivo de contrarresto
        Effects = {          -- *Obligatorio* tabla por nivel (reemplaza los valores por nivel originales)
            { Level = 1, Probability = 0.55, Effect = 0.03, Duration = 5 },
            { Level = 2, Probability = 0.65, Effect = 0.05, Duration = 7 },
        }
    }
}

5.2 Campos de nivel superior modificables

5.3 Campos de Effects por nivel

5.4 Enums disponibles

5.5 Ejemplo completo (DemoCharacterMod/GeneBuff/gene_buff.txt incluido)

CharacterGeneBuff = {
    -- ① Sobrescribir los valores por nivel del gen existente Metabolism
    Metabolism = {
        Effects = {
            { Level = 1, Effect = 0.12, Skillful = 0   },
            { Level = 2, Effect = 0.18, Skillful = 100 },
        }
    },
    -- ② Sobrescribir la probabilidad de activación, valores y duración del gen de habilidad existente Bleed
    Bleed = {
        Effects = {
            { Level = 1, Probability = 0.55, Effect = 0.03, Duration = 5 },
            { Level = 2, Probability = 0.65, Effect = 0.05, Duration = 7 },
        }
    }
}

5.6 Otorgar genes innatos a una criatura

-- En el script CharacterAsset de la criatura, usa el campo gene para otorgar genes innatos. Formato: NombreDelGen,Nivel;
CharacterAsset = {
    race = "allo",
    gene = "Metabolism,2;",
}

5.7 Carga y restricciones

• Se aplica de inmediato: una vez que la sobrescritura tiene éxito, nacimiento / activación / ejecución leen los valores sobrescritos.
• Validación estricta de referencias: With debe ser tag,nivel, sin autorreferencia, la etiqueta referenciada debe existir y el nivel debe estar en rango; Copes debe existir y no autorreferenciarse. Cualquier fallo rechaza la sobrescritura (nunca falla en silencio).
• Sin Effects válidos → esa sobrescritura falla.
• Restauración por sesión: salir / desactivar / reiniciar el MOD restaura automáticamente los genes sobrescritos, evitando residuos entre partidas.
• Paridad en ambos lados: el servidor debe cargar el mismo MOD mediante GAME_MODS; los hashes deben coincidir para entrar; /modReload recarga los valores de genes en caliente.

6. MOD de skins

Usa la tabla CharacterSkin para añadir skins personalizadas a los personajes. Cada archivo .txt define una skin. Los archivos de textura van en la carpeta SkinsAsset/ dentro del directorio del MOD. Consulta el DemoSkinsMod incluido en el juego para ver un ejemplo completo.

6.1 Script de skin

CharacterSkin = {
    Race = "allo",                              -- *Obligatorio* etiqueta de raza
    Name = "Crooked mouth",                      -- *Obligatorio* nombre único de skin (para deduplicación)
    Path = "SkinsAsset/Crooked mouth.png",       -- *Obligatorio* ruta de textura (relativa a la raíz del MOD)
}

6.2 Requisitos de textura

• Formato: PNG o JPG.
• Resolución: se recomienda que coincida con la textura original (normalmente 2048×2048 o 4096×4096).
• La ruta debe ser relativa al directorio raíz del MOD, no usar rutas absolutas.

6.3 Ejemplo de directorio con múltiples skins

MySkinMod/
├── mod.json
├── preview.jpg
└── SkinsAsset/
    ├── allo_crooked.txt   ← CharacterSkin { Race="allo", Name="Crooked mouth", ... }
    ├── crooked_allo.png   ← Archivo de textura
    ├── rex_volcano.txt    ← Un mismo MOD puede contener skins de varias razas
    └── volcano_rex.png

7. Avanzado: Gestión y distribución

7.1 Sistema de prioridad

Cuando varios MODs modifican el mismo campo de la misma raza, el valor de Priority más alto se ejecuta después y prevalece. El valor por defecto es 0. Los MODs con la misma prioridad se ejecutan en orden alfabético.

7.2 Seguridad del sandbox Lua

• os, io: comandos del sistema y lectura/escritura de archivos están prohibidos.
• dofile, loadfile, package: ejecución de archivos locales arbitrarios y carga de bibliotecas dinámicas están prohibidos.

7.3 Empaquetar como archivo .mod

Comprime todos los archivos de la carpeta del MOD en un ZIP y luego cambia la extensión a .mod. Asegúrate de que mod.json esté en la raíz del archivo comprimido. Tanto .mod como .zip son reconocidos por el juego.

7.4 MODs del servidor

El servidor especifica los MODs a cargar mediante la variable de entorno GAME_MODS (separados por comas):
GAME_MODS=DemoCharacterMod,MySkinMod
Todos los MODs especificados por el servidor deben estar instalados y habilitados en el cliente para poder unirse. Los MODs adicionales habilitados solo en el cliente no surtirán efecto en ese servidor. Los administradores pueden usar /modReload para recargar la configuración de MODs en caliente.