============================================================
DUNE 2000 ACCESIBLE - GUÍA DE CREACIÓN DE MODS
============================================================

INTRODUCCIÓN
------------
Los mods permiten modificar cualquier aspecto del juego sin
tocar el código fuente. Esta guía explica cómo crear mods.

ESTRUCTURA DE UN MOD
--------------------
Cada mod es una carpeta dentro de data/mods/ con esta estructura:

  mi_mod/
    info.txt          Información del mod (obligatorio)
    reglas.txt        Definiciones del juego (opcional)
    ia.txt            Scripts de IA (opcional)
    facciones.txt     Facciones nuevas (opcional)
    sonidos/          Sonidos personalizados (opcional)
    musica/           Música personalizada (opcional)
    mapas/
      escaramuza/     Mapas de escaramuza (opcional)
      personalizados/ Mapas sueltos (opcional)
    campanas/         Historias/campañas personalizadas (opcional)
      mi_historia/
        info.txt      Título y descripción de la historia
        misiones.txt  Lista de misiones
        mapas/        Un archivo .txt por misión

ARCHIVO INFO.TXT
----------------
Contiene los metadatos del mod:

  nombre: Mi Mod Genial
  autor: Tu Nombre
  version: 1.0
  descripcion: Agrega nuevas unidades y edificios
  requiere: otro_mod

El campo "requiere" es opcional. Si se especifica, el sistema
activará automáticamente el mod requerido al activar este mod.
Se pueden especificar múltiples dependencias separadas por comas.

ARCHIVO REGLAS.TXT
------------------
Define o modifica unidades, edificios y mejoras.
Formato: cada entidad empieza con "def nombre" seguido
de sus propiedades.

Ejemplo - Nueva unidad:

  def super_tanque
  clase vehiculo
  vida_max 1500
  armadura 10
  velocidad 3
  dano 80
  alcance 6
  dano_splash 3
  costo_especia 1200
  tiempo_construccion 40
  poblacion 5
  requisitos fabrica_pesada alta_tecnologia
  rango_vision 6
  descripcion Super Tanque
  sonido_ataque canon_pesado
  sonido_movimiento tanque_mover

Ejemplo - Modificar unidad existente:

  def tanque_combate
  vida_max 900
  dano 45

(Solo las propiedades listadas se modifican, el resto
se mantiene del juego base)

Ejemplo - Nuevo edificio:

  def laboratorio
  clase edificio
  vida_max 1200
  armadura 3
  costo_especia 800
  tiempo_construccion 30
  requisitos alta_tecnologia
  puede_investigar super_armadura super_armas
  rango_vision 5
  descripcion Laboratorio Avanzado

CLASES DISPONIBLES:
- soldado: Unidad de infantería
- trabajador: Unidad recolectora (cosechadora)
- vehiculo: Vehículo terrestre
- aereo: Unidad aérea
- edificio: Estructura construible
- mejora: Investigación
- deposito: Recurso recolectable
- criatura: Entidad neutral (gusano de arena)

ASIGNACIÓN DE UNIDADES A EDIFICIOS:
Las unidades nuevas de un mod se asignan automáticamente
al edificio productor apropiado según su clase:
- soldado -> cuartel
- trabajador -> refinería
- vehiculo -> fábrica ligera
- aereo -> puerto espacial

Si prefieres asignar manualmente, redefine el edificio
en tu reglas.txt. Las listas se EXTIENDEN (no reemplazan):

  def cuartel
  puede_entrenar mi_soldado_especial

Esto añade mi_soldado_especial a la lista existente del
cuartel sin quitar las unidades base.

Si una unidad tiene requisitos (ej: requisitos alta_tecnologia),
el jugador necesitará ese edificio construido para entrenarla,
independientemente de en qué edificio se produzca.

PROPIEDADES NUMÉRICAS:
- vida_max: Puntos de vida máximos
- dano: Daño por ataque
- armadura: Reducción de daño recibido
- alcance: Rango de ataque (en casillas)
- velocidad: Velocidad de movimiento
- costo_especia: Costo en especia
- tiempo_construccion: Turnos para producir
- poblacion: Población que consume
- poblacion_provee: Población que otorga (edificios)
- capacidad_recoleccion: Especia máxima que carga
- cantidad_recoleccion: Especia por ciclo
- tiempo_recoleccion: Turnos por ciclo de recolección
- rango_vision: Rango de visión
- dano_splash: Radio de daño en área
- bonus_cuerpo_a_cuerpo: Daño extra al atacar en misma casilla
- ataque_en_movimiento: 1 para disparar mientras se mueve
- almacenamiento_especia: Capacidad de almacenamiento (edificios)
- evasion: Probabilidad de esquivar ataques (0-100)
- dano_vs_edificio: Multiplicador de daño contra edificios (ej: 2.0)
- energia_produccion: Energía que produce el edificio
- energia_consumo: Energía que consume el edificio
- limite_activos: Máximo de unidades de este tipo activas (ej: 5)

PROPIEDADES DE TEXTO:
- clase: Tipo de entidad
- faccion: Facción a la que pertenece
- descripcion: Nombre para mostrar
- tipo_dano: Tipo de daño (normal/perforante/explosivo/concusivo)
- tipo_armadura: Tipo de armadura (ligera/pesada/edificio/normal)
- sonido_ataque: Nombre del sonido de ataque
- sonido_muerte: Nombre del sonido de muerte
- sonido_seleccion: Nombre del sonido de selección
- sonido_movimiento: Nombre del sonido de movimiento

PROPIEDADES DE LISTA:
- puede_construir: Edificios que puede construir
- puede_entrenar: Unidades que puede entrenar
- puede_investigar: Mejoras que puede investigar
- requisitos: Edificios/mejoras necesarios
- puede_usar: Habilidades disponibles

ARCHIVO IA.TXT
--------------
Define comportamientos de IA personalizados.

Comandos disponibles:
- obtener N tipo: Produce N unidades/edificios del tipo
- atacar: Ordena atacar al enemigo
- etiqueta nombre: Define un punto de salto
- ir_a nombre: Salta a una etiqueta
- ir_aleatorio e1 e2: Salta a una etiqueta aleatoria
- ataques_constantes: Activa ataques automáticos
- investigar_auto: Investiga mejoras automáticamente
- vigilancia N: Tiempo máximo en una línea

Ejemplo:

  def mi_ia_agresiva
  ataques_constantes
  etiqueta inicio
  obtener 5 cosechadora 10 infanteria_pesada
  atacar
  obtener 5 cosechadora 10 tanque_combate
  atacar
  ir_a inicio

SONIDOS PERSONALIZADOS
----------------------
Coloca archivos .wav o .ogg en la carpeta sonidos/ del mod.
El nombre del archivo (sin extensión) debe coincidir con el
nombre usado en las propiedades de sonido.

Ejemplo: si defines sonido_ataque laser, crea el archivo
sonidos/laser.wav

Sonidos del sonar (6.5):
El sonar usa sonidos diferenciados por tipo de entidad.
Puedes personalizar estos sonidos en tu mod:
- sonar_aliado_infanteria: tono agudo para infantería aliada
- sonar_aliado_vehiculo: tono medio para vehículos aliados
- sonar_aliado_edificio: tono grave para edificios aliados
- sonar_aliado_aereo: tono sierra para aéreos aliados
- sonar_enemigo_infanteria: cuadrada para infantería enemiga
- sonar_enemigo_vehiculo: cuadrada para vehículos enemigos
- sonar_enemigo_edificio: cuadrada grave para edificios enemigos
- sonar_enemigo_aereo: sierra para aéreos enemigos
Si no existen los específicos, se usan sonar_aliado/sonar_enemigo.

Sonidos ambientales por terreno (7.2):
El juego reproduce sonidos de fondo al mover el cursor.
Puedes personalizar estos sonidos en tu mod:
- ambiente_arena: viento suave de fondo
- ambiente_dunas: viento en dunas
- ambiente_roca: crujidos de roca
- ambiente_montaña: silbido de montaña
- ambiente_ruinas: ecos en ruinas
- ambiente_especia: burbujeo de especia

Indicadores de salud (7.4):
Al seleccionar una unidad, suena un tono de salud:
- salud_buena: tono agudo (>75% vida)
- salud_media: tono medio (50-75%)
- salud_baja: tono grave (25-50%)
- salud_critica: alarma (<25%)

Sonidos de órdenes (7.3):
Cada orden tiene un sonido diferenciado:
- orden_mover, orden_atacar, orden_recolectar (ya existían)
- orden_patrullar, orden_capturar, orden_transportar,
  orden_descargar, orden_detener (nuevos en v2.5)

MÚSICA PERSONALIZADA
--------------------
Coloca archivos .wav o .ogg en la carpeta musica/ del mod.
Nombres reconocidos: menu, batalla, batalla_tensa,
batalla_epica, batalla_desesperacion, victoria, derrota.

FACCIONES NUEVAS
----------------
Crea facciones.txt con el formato:
  id|nombre|descripcion

Ejemplo:
  tleilaxu|Casa Tleilaxu|Maestros de la genética

Luego define las unidades especiales de la facción en
reglas.txt con la propiedad faccion.

MAPAS PERSONALIZADOS
--------------------
Los mapas usan formato de texto con secciones:

  [mapa]
  titulo Mi Mapa
  columnas 10
  filas 10
  ancho_casilla 12
  objetivo Destruye al enemigo.
  intro Texto de introducción.

  [terreno]
  col fila tipo [especia]

  [jugadores]
  nombre faccion equipo tipo col fila especia

  [edificios]
  jugador tipo col fila construido

  [unidades]
  jugador tipo col fila

  [recursos]
  tipo col fila cantidad

Tipos de terreno: arena, roca, especia, dunas, montaña,
  acantilado, cañón, ruinas, plataforma, especia_rica

EFECTOS DE TERRENO EN COMBATE:
- arena: terreno básico, sin efectos
- roca: construible, sin efectos de combate
- montaña: intransitable, bloquea visión y movimiento
- dunas: no construible, ralentiza unidades
- acantilado: intransitable, bloquea visión
- cañón: paso estrecho, transitable pero no construible
- ruinas: cobertura +2 armadura a unidades dentro
- plataforma: terreno elevado, +1 alcance a unidades encima
- especia_rica: campo de especia de alta concentración

USANDO EL EDITOR
-----------------
El editor de mods (EditorMods.exe) facilita la creación:
1. Ctrl+N para crear un nuevo mod
2. Menú Editar > Agregar entidad para agregar cualquier tipo:
   soldados, trabajadores, vehículos, aéreos, edificios,
   mejoras, recursos y criaturas
3. Edita las propiedades en el panel derecho
4. Para unidades (soldados, vehículos, etc.): usa el selector
   "Edificio productor" para asignar a qué edificio las entrena
5. Para mejoras: usa el selector "Edificio investigador"
6. Para edificios: las listas puede_entrenar, puede_construir
   y puede_investigar se editan directamente en las propiedades
7. F5 para validar
8. Ctrl+S para guardar
9. Ctrl+E para exportar como ZIP y compartir

ASIGNACIÓN DE UNIDADES EN EL EDITOR:
Cuando editas una unidad (soldado, vehículo, trabajador, aéreo),
el panel muestra un selector "Edificio productor" con todos los
edificios disponibles (del mod y del juego base).
- Selecciona un edificio para asignar la unidad a ese edificio
- Selecciona "(auto-asignar)" para que el juego decida según la clase
- Al guardar, el editor actualiza automáticamente las listas
  puede_entrenar de los edificios en reglas.txt

Para mejoras, funciona igual con "Edificio investigador" y
la lista puede_investigar.

Al eliminar una entidad, el editor limpia automáticamente
todas las referencias en edificios.

TECLAS DEL EDITOR:
- Ctrl+N: Nuevo mod
- Ctrl+O: Abrir mod existente
- Ctrl+S: Guardar mod
- Ctrl+Shift+S: Guardar como otro nombre
- Ctrl+D: Duplicar entidad seleccionada
- Delete: Eliminar entidad o audio seleccionado
- F5: Validar mod
- Ctrl+E: Exportar como ZIP
- Ctrl+Shift+I: Importar mod desde ZIP
- Ctrl+H: Editor de historias/campañas
- Ctrl+J: Editor de scripts de IA
- Ctrl+F: Editor de facciones
- Ctrl+K: Editor de teclas (data/teclas.ini)
- Ctrl+I: Información del mod

ÁRBOL DEL MOD:
El panel izquierdo muestra todo el contenido del mod organizado:
- Edificios, Soldados, Trabajadores, Vehículos, Aéreos,
  Mejoras, Recursos, Criaturas: entidades definidas en reglas.txt
- Sonidos: archivos de audio para efectos del mod
- Música: archivos de música para el mod

AGREGAR SONIDOS Y MÚSICA:
Usa los botones "+ Sonido" y "+ Música" debajo del árbol
para importar archivos de audio (.wav, .ogg, .mp3) desde
tu equipo. Los archivos se copian a la carpeta del mod.

Para usar un sonido en una entidad, asigna su nombre
(sin extensión) en las propiedades:
  sonido_ataque mi_sonido
  sonido_muerte mi_sonido
  sonido_seleccion mi_sonido
  sonido_movimiento mi_sonido

Para música, usa nombres reconocidos por el juego:
  menu, batalla, victoria, derrota,
  batalla_tensa, batalla_epica

Al exportar como ZIP, todos los sonidos y música se
incluyen automáticamente.

VALIDACIÓN DE SONIDOS:
Al validar (F5), el editor verifica que los sonidos
referenciados en las entidades existan en el mod o
en los sonidos del juego base.

CREAR HISTORIAS PERSONALIZADAS
------------------------------
Puedes crear historias completas jugables en Modo Historia.

MÉTODO 1: EDITOR DE HISTORIAS (recomendado)
1. Abre el editor de mods (EditorMods.exe)
2. Crea o abre un mod (Ctrl+N o Ctrl+O)
3. Ve a Herramientas > Editor de historias (Ctrl+H)
4. Pulsa "Nueva" para crear una historia
5. Escribe un ID (sin espacios, ej: mi_aventura)
6. Rellena el título y la descripción
7. Agrega misiones con "Agregar misión"
8. Cada misión crea un mapa plantilla automáticamente
9. Edita cada mapa con "Editar mapa" (incluye validación)
10. Pulsa "Guardar historia" para guardar
11. Activa el mod en el juego
12. Tu historia aparecerá en Modo Historia > Nueva historia

El editor de mapas integrado permite:
- Editar el texto del mapa directamente
- Validar el mapa antes de guardar (comprueba secciones,
  jugadores, terreno, etc.)
- Validar balance del mapa (acceso a recursos, distancias
  entre bases, jugadores encerrados, distribución de recursos)
- Guardar cambios al archivo

EDITOR DE FACCIONES (Ctrl+F):
Crea facciones nuevas para tu mod. Cada facción tiene:
- ID: identificador interno (sin espacios)
- Nombre: nombre visible en el juego
- Descripción: texto descriptivo
Las facciones se guardan en facciones.txt del mod.

EDITOR DE IA (Ctrl+J):
Edita los scripts de inteligencia artificial del mod.
Se abre un editor de texto con el archivo ia.txt.
Si no existe, se crea con una plantilla de ejemplo.

MÉTODO 2: ARCHIVOS DE TEXTO
1. Dentro de tu mod, crea:
   campanas/mi_historia/info.txt
   campanas/mi_historia/misiones.txt
   campanas/mi_historia/mapas/

2. info.txt:
   titulo: Mi Historia Épica
   descripcion: Una aventura en Arrakis.

3. misiones.txt (formato: id|numero|nombre):
   mision_1|1|El comienzo
   mision_2|2|La batalla
   mision_3|3|El final

4. Crea un mapa por misión en mapas/:
   mapas/mision_1.txt
   mapas/mision_2.txt
   mapas/mision_3.txt

5. Cada mapa sigue el formato estándar de mapas
   (ver sección MAPAS PERSONALIZADOS arriba)

CONDICIONES DE VICTORIA EN MAPAS:
- Sin condición: destruir todos los enemigos
- condicion_victoria recolectar + objetivo_especia N:
  Acumular N especia
- condicion_victoria construir + objetivo_edificio tipo:
  Construir un edificio específico
- condicion_victoria capturar + objetivo_capturar tipo:
  Capturar un edificio enemigo del tipo indicado
- condicion_victoria contrarreloj + objetivo_turnos_limite N:
  Sobrevivir N turnos
- condicion_victoria escoltar + objetivo_turnos_limite N:
  Mantener una unidad viva durante N turnos
- Se pueden combinar: recolectar especia Y construir edificio

SECCIONES DE HISTORIA EN MAPAS (8.1/8.4):
Los mapas de misión pueden incluir secciones adicionales
para enriquecer la narrativa y la jugabilidad:

  [briefing]
  Texto que se lee antes de iniciar la misión.
  Puede tener varias líneas. Se unen con espacios.

  [debriefing_victoria]
  Texto que se lee al ganar la misión.

  [debriefing_derrota]
  Texto que se lee al perder la misión.

  [triggers]
  Eventos scripted que se activan durante la partida.
  Formato: id|condicion|valor|accion|parametros...

  Condiciones disponibles:
  - turno|N: se activa cuando el turno >= N
  - turno_exacto|N: se activa en el turno exacto N
  - especia|N: se activa cuando el jugador tiene >= N especia
  - unidades|N: se activa cuando el jugador tiene >= N unidades
  - edificio_destruido|tipo: se activa si el jugador pierde
    un edificio del tipo indicado
  - casilla_explorada|col|fila: se activa al explorar esa casilla
  - enemigos_eliminados|N: se activa cuando quedan <= N enemigos

  Acciones disponibles:
  - mensaje|texto: muestra un mensaje al jugador
  - refuerzos|tipo_unidad|cantidad|col|fila: spawn de aliados
  - refuerzos_enemigos|tipo_unidad|cantidad|col|fila: spawn enemigos
  - objetivo|texto: cambia el objetivo de la misión
  - especia|cantidad: da bonus de especia al jugador

  Ejemplo de triggers:
  1|turno|20|mensaje|Los exploradores reportan movimiento enemigo al norte.
  2|turno|50|refuerzos|tanque_combate|2|3|3
  3|especia|5000|mensaje|Excelente recolección. El Emperador está complacido.
  4|enemigos_eliminados|3|refuerzos_enemigos|infanteria_pesada|5|12|12

DECISIONES NARRATIVAS EN MISIONES.TXT (8.3):
Puedes añadir decisiones que bifurcan la historia.
Formato en misiones.txt:
  decision|numero|pregunta|id_mision_a|texto_opcion_a|id_mision_b|texto_opcion_b

Ejemplo:
  mision_3|3|Defensa del puesto avanzado
  decision|4|¿Atacas o defiendes?|mision_4a|Atacar|mision_4b|Defender
  mision_4a|4|Contraataque (si eligió atacar)
  mision_4b|4|Defensa del convoy (si eligió defender)
  mision_5|5|La batalla continúa

Al llegar a la decisión, el jugador elige una opción y
salta directamente a la misión correspondiente.

TIPOS DE IA PARA ENEMIGOS:
- facil: IA básica, pocos ataques
- equilibrado: IA media, ataques moderados
- agresivo: IA difícil, ataques constantes

CONSEJOS PARA BUENAS HISTORIAS:
- Empieza con misiones fáciles y ve aumentando la dificultad
- Usa misiones de recolección al principio como tutorial
- Varía los objetivos: recolectar, construir, destruir
- Escribe intros narrativas para cada misión
- Usa mapas más grandes para misiones finales
- Incluye múltiples enemigos en misiones avanzadas

HOT-RELOAD DE MODS (v2.8)
--------------------------
Puedes recargar las definiciones de mods sin reiniciar el juego:

Desde el editor:
- Herramientas > Recargar mods en juego (F6)
- Recarga reglas.txt base y aplica todos los mods activos

Desde código (para modders avanzados):
  from engine.mods import recargar_mods
  defs = recargar_mods()

Esto permite iterar rápidamente al crear mods sin tener
que cerrar y abrir el juego cada vez.

NUEVAS PROPIEDADES DE ENTIDADES (v2.7-2.9)
-------------------------------------------
evasion           Probabilidad de esquivar (0-100, ej: 15)
dano_vs_edificio  Multiplicador de daño contra edificios (ej: 2.0)
energia_produccion Energía que produce el edificio (ej: 100)
energia_consumo   Energía que consume el edificio (ej: 30)
limite_activos    Máximo de unidades de este tipo activas (ej: 5)
orientacion       Orientación del edificio en grados (0/90/180/270)
sector_disparo    Arco de disparo de torreta en grados (360=omni)
anfibio           1 para unidades que van por tierra y agua
clase naval       Unidades que solo van por agua

NUEVOS TERRENOS (v2.9)
-----------------------
agua              Terreno acuático (solo navales/anfibios)

NUEVAS CLASES DE UNIDAD (v2.9)
-------------------------------
naval             Unidades que solo se mueven por agua
                  Ejemplo: barcaza, fragata

NUEVA FACCIÓN: FREMEN (v2.9)
------------------------------
Los Fremen son una facción jugable con unidades únicas:
- guerrillero_fremen: infantería rápida con evasión
- fedaykin: élite cuerpo a cuerpo
- jinete_gusano: vehículo pesado
Edificio base: sietch_fremen

CONDICIONES DE VICTORIA EN MAPAS
---------------------------------
condicion_victoria recolectar    Recolectar X especia
condicion_victoria construir     Construir edificio específico
condicion_victoria defender      Sobrevivir N turnos
condicion_victoria capturar      Capturar edificio con ingeniero
condicion_victoria contrarreloj  Sobrevivir hasta turno límite
condicion_victoria escoltar      Mantener unidad viva N turnos
condicion_victoria supervivencia Oleadas infinitas (sin victoria)

Propiedades asociadas:
  objetivo_especia N          Cantidad de especia requerida
  objetivo_edificio tipo      Tipo de edificio a construir/capturar
  objetivo_turnos_limite N    Turnos máximos
  objetivo_capturar tipo      Tipo de edificio a capturar
