Home

XiloAdventures - Guia Completa

Motor de aventuras de texto con editor visual, scripting grafico e inteligencia artificial

Bienvenido a XiloAdventures

XiloAdventures es un ecosistema completo para crear y jugar aventuras de texto conversacionales. Desarrollado en .NET 8 con WPF, ofrece un editor visual intuitivo, un sistema de scripting basado en nodos y opciones de inteligencia artificial.

Caracteristicas Principales

Categoria	Funcionalidades
Editor Visual	Mapa interactivo, drag & drop, zoom/pan, grid, undo/redo completo
Scripting	50+ tipos de nodos, eventos, condiciones, acciones, control de flujo
NPCs	Comercio, conversaciones, patrullas automaticas, seguimiento del jugador
Audio	Musica global/por sala, efectos, TTS con fade y talkover automatico
Exportacion	EXE independiente (~80-100 MB) sin dependencias externas
IA Opcional	Generacion de mundos, interpretacion de comandos, imagenes, voz

Indice de Documentacion

Pagina	Descripcion
Editor de Mundos	Crea y edita mundos, salas, objetos, NPCs, puertas y misiones
Sistema de Scripts	Programa comportamientos con nodos visuales (50+ tipos)
Ventana del Jugador	Comandos, inventario, conversaciones y funciones de juego

Arquitectura del Proyecto

XiloAdventures se compone de 5 proyectos .NET 8:

XiloAdventures.sln
├── XiloAdventures.Engine        # Motor de juego (libreria)
│   ├── Engine/                  # Motores principales
│   │   ├── GameEngine.cs        # Orquestador principal
│   │   ├── Parser.cs            # Parser de comandos naturales
│   │   ├── ScriptEngine.cs      # Ejecucion de scripts visuales
│   │   ├── ConversationEngine.cs# Motor de dialogos
│   │   ├── DoorService.cs       # Logica de puertas/llaves
│   │   ├── SoundManager.cs      # Gestion de audio (NAudio)
│   │   ├── SaveManager.cs       # Guardado/carga de partidas
│   │   └── WorldLoader.cs       # Carga de mundos .xaw
│   └── Models/                  # Modelos de datos
│       ├── Models.cs            # WorldModel, Room, GameObject, Npc...
│       ├── ScriptModels.cs      # ScriptDefinition, ScriptNode...
│       ├── ConversationModels.cs# Dialogos y tienda
│       └── NodeTypeRegistry.cs  # 50+ tipos de nodos (2281 lineas)
│
├── XiloAdventures.Wpf           # Editor visual (WPF)
├── XiloAdventures.Wpf.Common    # Componentes compartidos
├── XiloAdventures.Wpf.Player    # Player standalone
└── XiloAdventures.Tests         # 838+ tests (xUnit)

Inicio Rapido (Ventana de Startup)

Al abrir XiloAdventures, veras la ventana de inicio con todas las opciones principales:

Barra de Herramientas Superior

Icono	Accion	Descripcion
+	Nuevo Mundo	Crea un mundo vacio y abre el editor
-	Eliminar Mundo	Borra permanentemente el mundo seleccionado
Carpeta	Abrir Carpeta	Abre la carpeta `worlds/` en el explorador
Actualizar	Actualizar Lista	Recarga la lista de mundos disponibles
Estrella	Generador IA	Abre el generador de mundos con inteligencia artificial
Corazon	Donaciones	Enlace a PayPal para apoyar el proyecto

Lista de Mundos

Muestra todos los archivos .xaw de la carpeta worlds/
Doble clic en un mundo para abrirlo en el editor
Ordenados alfabeticamente

Botones de Accion Principal

Boton	Funcion
Nueva partida	Inicia una nueva partida con el mundo seleccionado
Cargar partida	Carga una partida guardada (archivos `.xas`)
Editor	Abre el mundo en el editor para modificarlo
Salir	Cierra la aplicacion

Opciones de Nueva Partida

Al iniciar una nueva partida, puedes configurar:

Sonido

Activa o desactiva el audio del juego
Volumenes independientes: master, musica, efectos, voz
Fade automatico entre pistas de musica (0.5 segundos)
Talkover: reduce musica 50% durante narracion

Usar IA

Habilita funciones de inteligencia artificial:

Funcion	Requisito	Descripcion
Interpretacion de comandos	Ollama (Docker)	La IA entiende comandos escritos de forma natural
Voz narrativa	Coqui TTS (Docker)	Lee en voz alta las descripciones de las salas
Generacion de imagenes	Stable Diffusion (Docker)	Crea imagenes para las salas

Requisito: Docker Desktop debe estar instalado y en ejecucion para usar las funciones de IA.

Servicios Docker Opcionales

Servicio	Contenedor	Funcion
Ollama	xilo-ollama	LLM (modelo llama3) para generacion de contenido
Coqui TTS	xilo-tts (puerto 5002)	Conversion texto-a-voz
Stable Diffusion	xilo-stablediffusion	Generacion de imagenes

Estructura de Archivos

XiloAdventures/
├── worlds/              # Mundos creados (.xaw)
├── saves/               # Partidas guardadas (.xas)
├── config.xac           # Configuracion global
└── config_[worldId].xac # Configuracion por mundo

Formatos de Archivo

Extension	Tipo	Descripcion	Formato
`.xaw`	Mundo	Salas, objetos, NPCs, scripts, configuracion	JSON + ZIP + Base64 + AES-CBC
`.xas`	Partida	Estado guardado de una partida en progreso	JSON + AES-CBC
`.xac`	Config	Ajustes de sonido, IA y preferencias	JSON + AES-CBC

Encriptacion

Los mundos pueden protegerse con una clave de encriptacion:

Clave del mundo: 8 caracteres, configurada en el editor (Propiedades del Juego)
Cifrado: AES-CBC con padding automatico a 32 bytes
Se solicita al iniciar o cargar partida
Protege el contenido del archivo .xaw

Claves por Defecto

Tipo	Clave	Uso
Mundos	`XiloAdv-Key-1234XiloAdv-Key-1234`	Si no se especifica clave
Partidas	`XiloAdventuresXiloAdventuresXilo`	Partidas guardadas

Sistemas Principales del Motor

Sistema de Tiempo y Clima

Caracteristica	Descripcion
Hora del juego	0-23 horas, configurable
Minutos por hora	Cuantos minutos reales equivalen a 1 hora de juego
Fases del dia	Madrugada (0-5), Manana (6-11), Tarde (12-17), Noche (18-23)
Clima	Despejado, Lluvioso, Nublado, Tormenta

Sistema de NPCs

Funcionalidad	Descripcion
Estadisticas	Level, Strength, Dexterity, Intelligence, MaxHealth, Gold
Comercio	IsShopkeeper, ShopInventory, BuyPriceMultiplier, SellPriceMultiplier
Patrulla	PatrolRoute (lista de salas), PatrolSpeed, IsPatrolling
Seguimiento	IsFollowingPlayer, FollowSpeed (100 = igual que jugador)

Sistema de Objetos

Propiedad	Descripcion
Tipo	Ninguno, Arma, Armadura, Casco, Escudo, Comida, Bebida, Llave
Fisicas	Weight (gramos), Volume (cm3), Price (monedas)
Contenedor	IsContainer, MaxCapacity, IsOpenable, IsLocked, KeyId
Gramatica	Gender (Masculine/Feminine), IsPlural (el/la, los/las)
Iluminacion	IsLightSource, IsLit, LightTurnsRemaining, CanIgnite, CanExtinguish
Fabricacion	CraftingRecipe (lista de ingredientes)

Sistema de Equipamiento

Ranura	Tipos aceptados	Slot en NPC/Jugador
Mano derecha	Arma, Escudo	EquippedRightHandId
Mano izquierda	Arma (1 mano), Escudo	EquippedLeftHandId
Torso	Armadura	EquippedTorsoId
Cabeza	Casco	EquippedHeadId

Sistema de Puertas

Caracteristica	Descripcion
Bidireccionales	Conectan dos salas (RoomIdA, RoomIdB)
Estados	IsOpen, IsLocked
Restriccion de lado	Both, FromAOnly, FromBOnly
Llave requerida	KeyObjectId

Sistema de Inteligencia Artificial

XiloAdventures integra funcionalidades de IA opcionales que se ejecutan mediante contenedores Docker. Todas las funciones de IA son completamente opcionales y el juego funciona perfectamente sin ellas.

Requisitos

Requisito	Descripcion
Docker Desktop	Debe estar instalado y en ejecucion
Espacio en disco	~15-20 GB para todos los modelos
RAM	Minimo 8 GB recomendado
GPU (opcional)	NVIDIA con CUDA para Stable Diffusion mas rapido

Contenedores Docker

Contenedor	Imagen	Puerto	Funcion
xilo-ollama	ollama/ollama:latest	11434	LLM (llama3)
xilo-tts	ghcr.io/idiap/coqui-tts-cpu:latest	5002	Texto-a-voz en espanol
xilo-stablediffusion	gadicc/diffusers-api:latest	7860	Generacion de imagenes

Los contenedores se descargan automaticamente la primera vez (puede tardar 10-20 minutos por servicio).

Funcionalidades de IA en el Editor

1. Generador de Mundos con IA (Menu IA -> Generador)

Genera mundos completos usando ChatGPT, Claude u otro LLM externo:

Configura los parametros:
- Tematica del mundo (fantasia medieval, ciencia ficcion, horror gotico...)
- Numero de salas (1-50)
- Cantidad de puertas, NPCs, misiones
- Tipos de objetos (armas, armaduras, comida, llaves, textos...)
Copia el prompt generado
Pegalo en ChatGPT, Claude, etc.
Descarga el archivo .xaw generado
Importalo en XiloAdventures

El prompt incluye:

Estructura JSON completa del mundo
Tipos de nodos de scripts disponibles
Reglas de consistencia (llaves accesibles, puertas conectadas)
Estadisticas del jugador (suma = 100 puntos)
Formato de coordenadas para el mapa

2. Generador de Datos por Lotes (Menu IA -> Generar Datos)

Genera contenido automaticamente para multiples entidades:

Funcion	Servicio	Descripcion
Crear descripciones	Ollama	Genera descripciones atmosfericas para salas sin descripcion
Corregir articulos	Ollama	Determina genero gramatical (el/la) de objetos y puertas
Generar imagenes	Stable Diffusion + Ollama	Crea imagenes pixel art para salas
Proceso completo	Todos	Ejecuta las tres funciones en orden

Crear descripciones de salas:

Usa el tema del mundo para coherencia
Considera si es interior/exterior
Incluye objetos presentes en la sala
Genera 2-3 frases atmosfericas

Corregir generos gramaticales:

Analiza el nombre de cada objeto/puerta
Determina si es masculino/femenino
Detecta si es singular/plural
Solo procesa elementos no editados manualmente

Generar imagenes:

Requiere descripcion en todas las salas
Genera prompt en ingles optimizado para CLIP (max 77 tokens)
Estilo: pixel art, 16-bit, retro game
Tamano: 896x256 pixels (formato panoramico)
Modelo: Stable Diffusion v1.5

Funcionalidades de IA en Tiempo de Juego

Interpretacion de Comandos

Cuando el parser no entiende un comando:

El jugador escribe algo como "dame la espada del suelo"
El parser no reconoce el formato
Se envia a Ollama para interpretar
Ollama traduce a comando valido: "coger espada"
Se ejecuta el comando traducido

Ejemplo:

> quiero agarrar esa cosa brillante
(Consultando a la IA)...
-> Interpretado como: coger gema
Has cogido la gema.

Voz Narrativa (TTS)

Lee las descripciones de sala en voz alta:

Caracteristica	Descripcion
Modelo	tts_models/es/css10/vits (espanol)
Cache	Las voces generadas se almacenan para reutilizar
Talkover	Reduce musica al 50% durante la narracion
Pre-carga	Genera voces de salas adyacentes anticipadamente

Configuracion de IA

En las opciones del juego:

Opcion	Descripcion
Usar IA para comandos	Activa interpretacion con Ollama
Volumen de voz	Control independiente para TTS (0-100)
Sonido activado	Debe estar activo para TTS

Deteccion de GPU

Para Stable Diffusion, el sistema detecta automaticamente si hay GPU NVIDIA:

Con GPU NVIDIA + CUDA: Usa aceleracion por hardware (30-60 seg/imagen)
Sin GPU compatible: Usa CPU (varios minutos/imagen)

Tiempos de Espera

Operacion	Tiempo tipico
Primera descarga de Ollama	10-15 minutos
Primera descarga de Coqui TTS	10-15 minutos
Primera descarga de Stable Diffusion	10-20 minutos
Descarga modelo llama3	5-15 minutos
Generacion de descripcion	5-15 segundos
Determinacion de genero	3-8 segundos
Generacion de imagen (GPU)	30-60 segundos
Generacion de imagen (CPU)	2-5 minutos
Generacion de voz TTS	2-5 segundos

Arranque Automatico de Docker

Si Docker Desktop no esta ejecutandose:

XiloAdventures detecta que Docker no responde
Intenta arrancar Docker Desktop automaticamente
Espera hasta 2 minutos a que Docker este listo
Si no consigue arrancarlo, muestra mensaje de error

Flujo de Trabajo Recomendado

1. Crear nuevo mundo
       |
2. Disenar en el Editor
   - Salas y conexiones
   - Objetos y NPCs
   - Puertas y llaves
       |
3. Programar comportamientos
   - Scripts visuales (50+ tipos de nodos)
   - Conversaciones con emociones
   - Misiones y objetivos
       |
4. Probar el juego
   - Ctrl+P en el editor
   - El estado se preserva al modificar cosas del editor
       |
5. Exportar a EXE
   - Distribuye tu aventura sin dependencias

Tests y Calidad

El proyecto incluye 838+ tests unitarios y de integracion:

Componente	Tests
GameEngine	36
Parser	41
DoorService	12
NodeTypeRegistry	27
ScriptValidator	10
Integracion	36
Otros	15

Enlaces Utiles

Editor de Mundos - Guia completa del editor
Sistema de Scripts - Referencia de nodos (50+ tipos)
Ventana del Jugador - Comandos y funciones
Licencia

Te gusta XiloAdventures? Considera hacer una donacion!

Home

XiloAdventures - Guia Completa

Bienvenido a XiloAdventures

Caracteristicas Principales

Indice de Documentacion

Arquitectura del Proyecto

Inicio Rapido (Ventana de Startup)

Barra de Herramientas Superior

Lista de Mundos

Botones de Accion Principal

Opciones de Nueva Partida

Sonido

Usar IA

Servicios Docker Opcionales

Estructura de Archivos

Formatos de Archivo

Encriptacion

Claves por Defecto

Sistemas Principales del Motor

Sistema de Tiempo y Clima

Sistema de NPCs

Sistema de Objetos

Sistema de Equipamiento

Sistema de Puertas

Sistema de Inteligencia Artificial

Requisitos

Contenedores Docker

Funcionalidades de IA en el Editor

1. Generador de Mundos con IA (Menu IA -> Generador)

2. Generador de Datos por Lotes (Menu IA -> Generar Datos)

Funcionalidades de IA en Tiempo de Juego

Interpretacion de Comandos

Voz Narrativa (TTS)

Configuracion de IA

Deteccion de GPU

Tiempos de Espera

Arranque Automatico de Docker

Flujo de Trabajo Recomendado

Tests y Calidad

Enlaces Utiles

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally