Guía para crear plugins en TheoTown

TheoTown no es solo un juego de construcción de ciudades; es un lienzo en blanco para la creatividad. Una de sus características más potentes es la capacidad de expandir el contenido a través de plugins creados por la comunidad. Si alguna vez has soñado con ver tus propios edificios, parques o decoraciones en el juego, estás en el lugar correcto. Esta guía completa te llevará de la mano a través de todo el proceso, desde la configuración inicial hasta la creación de tu primer plugin funcional. No necesitas ser un programador experto, solo un poco de paciencia y ganas de aprender. ¡Vamos a construir algo increíble!

¿Qué Necesitas para Empezar?

Antes de sumergirnos en el código y los píxeles, es importante entender los componentes básicos de un plugin de TheoTown. En esencia, un plugin es una carpeta que contiene:

• Archivos de imagen: Los gráficos de tu edificio o decoración en formato .png.
• Archivos JSON: Archivos de texto plano que le dicen al juego cómo usar esas imágenes y qué propiedades tiene tu creación (por ejemplo, si es una casa, una tienda, etc.).
• Un archivo de manifiesto: Un archivo especial, también en formato JSON, que describe tu plugin al juego para que pueda gestionarlo correctamente.

La clave de todo el proceso es el formato JSON (JavaScript Object Notation), una forma estructurada y legible de almacenar información. No te asustes por el nombre; verás que es muy intuitivo.

Paso 1: Localiza la Carpeta de Plugins

Lo primero es lo primero: necesitas saber dónde colocar los archivos de tu plugin. La ubicación varía según tu sistema operativo:

• PC (Windows):C:/Users/TuNombreDeUsuario/TheoTown
• PC (MacOS y Linux):~/TheoTown
• Android:Android/data/info.flowersoft.theotown.theotown/files. Es posible que necesites un gestor de archivos que te permita acceder a esta ruta o usar el explorador de archivos integrado en el juego desde la vista de la región.
• iOS: Puedes acceder a los archivos a través de la aplicación "Archivos" o conectando tu dispositivo a un Mac y buscándolo en el Finder.

Dentro de esta carpeta, debes crear un nuevo directorio para cada plugin que hagas. Por ejemplo, si vas a crear un invernadero, podrías crear una carpeta llamada "MiInvernadero". Toda la magia ocurrirá dentro de esa carpeta.

Paso 2: El Corazón del Plugin, el Archivo JSON

Dentro de la carpeta de tu plugin, crea un nuevo archivo de texto y nómbralo como quieras, pero con la extensión .json (por ejemplo, invernadero.json). Este archivo definirá tu edificio. Un archivo JSON básico para un edificio residencial se ve así:

[{ "id": "$tunombre.invernadero.res01", "type": "residential", "author": "Tu Nombre", "width": 2, "height": 2, "level": 2, "frames": [{ "bmp": "invernadero.png" }] }]

Analicemos cada propiedad:

• id: Es el identificador único de tu edificio. Es crucial que sea único para evitar conflictos con otros plugins. Una buena práctica es empezar con un prefijo personal (ej: `$tunombre.`). Una vez publicado, no deberías cambiarlo, ya que las ciudades guardadas lo usan para identificar el edificio.
• type: Define el tipo de edificio. Puede ser residential, commercial, industrial, park, entre otros.
• author: Aquí pones tu nombre o apodo como creador del plugin.
• width y height: Definen el tamaño de la base del edificio en cuadrículas del juego. En TheoTown, los edificios deben tener una base cuadrada, por lo que ambos valores deben ser iguales.
• level: Para edificios residenciales, comerciales e industriales, define el nivel de riqueza/densidad. 1 para T (bajo), 2 para TT (medio) y 3 para TTT (alto).
• frames: Esta es una de las partes más importantes. Es una lista que contiene los gráficos del edificio. La propiedad bmp apunta al nombre del archivo de imagen (en este caso, "invernadero.png") que debe estar en la misma carpeta.

Paso 3: Creando los Gráficos

El aspecto visual de tu plugin es fundamental. TheoTown utiliza una perspectiva isométrica, y cada cuadrícula (tile) en el juego mide 32x16 píxeles. Esto significa que la base de tu edificio debe respetar estas dimensiones.

Por ejemplo, un edificio de 2x2 como el de nuestro ejemplo necesita una imagen cuya base ocupe al menos 64x32 píxeles. La altura del edificio puede variar.

Tabla de Dimensiones de Base

Una nota muy importante sobre los gráficos: respeta los derechos de autor. Utiliza únicamente gráficos creados por ti o para los que tengas permiso explícito de uso. Tomar imágenes de otros juegos o de internet sin permiso puede acarrear consecuencias.

Paso 4: El Manifiesto del Plugin (`plugin.manifest`)

Tu plugin podría funcionar sin este archivo, pero es una muy mala práctica. El archivo plugin.manifest es esencial para que el juego identifique tu plugin en la interfaz de usuario, lo gestione correctamente y funcione en el modo online. Crea un archivo llamado exactamente plugin.manifest en la raíz de la carpeta de tu plugin.

Su estructura es la siguiente:

{ "id": "GENERAR-UN-UUID-UNICO-AQUI", "version": 1, "title": "Mi Plugin de Invernadero", "text": "Un hermoso invernadero para tus ciudadanos.", "author": "Tu Nombre", "thumbnail": "invernadero.png" }

• id: Este es un identificador único para el plugin en su conjunto. Puedes usar un generador de UUID online para obtener uno.
• version: Un número que indica la versión de tu plugin. Deberías incrementarlo cada vez que lo actualices.
• title: El nombre de tu plugin que se mostrará en el juego.
• text: Una breve descripción.
• author: Tu nombre de autor.
• thumbnail: El nombre del archivo de imagen que se usará como miniatura en la lista de plugins.

Funcionalidad Avanzada: Animaciones y Rotaciones

Puedes hacer que tus plugins sean mucho más dinámicos. Por ejemplo, puedes añadir luces que se enciendan por la noche o crear edificios que se vean diferentes según la rotación.

Añadiendo Luces Nocturnas

Para añadir una animación de luz, primero defines la animación como un objeto separado en tu archivo JSON y luego la asocias a tu edificio.

[ { "id": "$tunombre.invernadero.luz", "type": "animation", "light": true, "light switching": true, "frames": [{ "bmp": "luz_noche.png" }] }, { "id": "$tunombre.invernadero.res01", "type": "residential", "author": "Tu Nombre", "width": 2, "height": 2, "level": 2, "frames": [{ "bmp": "invernadero.png" }], "frames winter": [{ "bmp": "invernadero_invierno.png" }], "animation": [{ "id": "$tunombre.invernadero.luz", "x": 0, "y": -36 }] } ]

Aquí hemos añadido un nuevo objeto de tipo animation con su propio `id`. Luego, en el objeto del edificio, lo llamamos usando la propiedad animation, especificando su `id` y las coordenadas (x, y) donde se debe dibujar la animación sobre el gráfico principal del edificio. También hemos añadido frames winter para que el edificio tenga una apariencia diferente en invierno.

Solución de Problemas: ¿Mi Plugin no Funciona?

Es normal encontrar errores al principio. Si tu plugin no aparece o el juego muestra un error, aquí tienes una lista de comprobación:

1. Errores de sintaxis JSON: Una coma mal puesta, un corchete que no se cierra o unas comillas olvidadas son los errores más comunes. Utiliza un validador de JSON online para comprobar tu código.
2. Nombres de archivo incorrectos: Asegúrate de que los nombres de los archivos de imagen en tu JSON (ej: "bmp": "invernadero.png") coinciden exactamente con los nombres de tus archivos, incluyendo mayúsculas y minúsculas.
3. Revisa el `error.log`: Cuando hay un problema con un plugin, TheoTown a menudo crea un archivo llamado error.log dentro de la carpeta de ese plugin. Ábrelo, ya que suele dar pistas muy claras sobre lo que ha fallado.
4. Estructura de carpetas: Confirma que cada plugin está en su propia carpeta y que todos los archivos necesarios están dentro de ella.

Preguntas Frecuentes (FAQ)

¿Puedo crear edificios con formas no cuadradas?

No. La base del edificio debe ser siempre cuadrada, lo que significa que las propiedades width y height en el JSON deben tener el mismo valor.

¿Cuál es el tamaño máximo para un edificio?

El tamaño máximo de la base es de 8x8 cuadrículas y la altura máxima de la imagen es de 256 píxeles.

¿Cómo añado funcionalidades personalizadas, como generar más dinero o electricidad?

El archivo JSON es principalmente descriptivo. La funcionalidad del edificio depende del type y otras propiedades que el juego ya entiende. Para comportamientos más complejos, es posible usar scripts de Lua, aunque eso es un tema mucho más avanzado.

¿Es realmente necesario el archivo `plugin.manifest`?

Sí, es altamente recomendable. Sin él, tu plugin no se mostrará correctamente en la interfaz de gestión de plugins, no funcionará online y podría dejar de ser compatible en futuras actualizaciones del juego.

Crear plugins para TheoTown es una experiencia increíblemente gratificante que te permite dejar tu huella personal en el juego. Aunque al principio pueda parecer complicado, una vez que entiendes la lógica de los archivos JSON y la estructura de los gráficos, el único límite es tu imaginación. ¡Ahora abre tu editor de texto, tu programa de dibujo y empieza a construir la ciudad de tus sueños!