Crear un módulo: de la investigación a la publicación
El procedimiento completo para crear un módulo de juego fiable: investigación, pruebas con el servidor real, entornos de ejecución portables, el aislamiento, los modos de consola y pruebas en un PC real.
Crear un módulo: de la investigación a la publicación
La guía de desarrollo de módulos explica qué contiene un módulo. Esta página explica cómo crear un módulo que funcione en un PC real.
Un módulo que pasa todas las pruebas unitarias puede fallar en un servidor real. El módulo de Terraria es un ejemplo. Pasó todas las pruebas unitarias y todas las comprobaciones de conformidad. En un servidor real tenía nueve defectos. Esta página muestra el procedimiento que encuentra esos defectos antes de publicar.
1. Reglas de diseño
Estas reglas se aplican a todos los módulos.
- El daemon hace el trabajo. Un módulo solo describe un juego. No evite el contrato del daemon. Si al contrato le falta una función que necesita, añada primero un punto de extensión general en el daemon.
- No ramifique por nombre de juego. El daemon y las utilidades compartidas no contienen nombres de juegos. Use claves de
module.toml, hooks y slots. - El mismo entorno de ejecución en todas partes. No use un entorno de ejecución instalado en el PC. El módulo descarga una versión fija y la coloca en la carpeta del servidor (sección 5).
- Cada valor en un solo lugar. El valor predeterminado de un ajuste viene de un archivo: el que crea el juego o el archivo de ejemplo de la descarga.
- Todo el texto para usuarios va en
locales/.en.jsones el archivo de referencia.
2. Investigar el juego
Antes de escribir código, cree una tabla de investigación en <game>/RESEARCH.md. Escriba la fuente de cada elemento. Indique también si la fuente es un documento o una medición. Si no encuentra una fuente, deje el elemento vacío y escriba "no verificado". No adivine valores.
| Elemento | Dónde encontrarlo |
|---|---|
| Ejecutable del servidor, argumentos de inicio, puertos predeterminados | Documentos oficiales, la ayuda del servidor, los scripts de inicio de la descarga |
| Todos los comandos y sus argumentos | Documentos oficiales de comandos y la salida del comando help del servidor. Compare ambos línea por línea |
| Todos los ajustes (clave, formato, rango, valor predeterminado) | El archivo de ajustes predeterminado que crea el servidor. Si no crea ninguno, use el archivo de ejemplo de la descarga |
| Sintaxis y codificación del archivo de ajustes | Los bytes originales de ese archivo |
| Partidas guardadas y las copias que crea el juego | La lista de archivos después de iniciar el servidor y guardar el mundo |
| Mensajes de listo, parada, entrada y salida | La salida original de la consola. Compruebe también si el ajuste de idioma del servidor traduce estos mensajes |
| Método de instalación y verificación de archivos | La dirección oficial de descarga y la suma de verificación oficial. Si no hay suma, escriba "ninguna" y la fuente |
| Requisitos de ejecución | Las referencias del ejecutable del servidor y los documentos oficiales. Busque lo que la descarga no incluye |
| Archivos fuera de la carpeta de instancia | Cambios en la carpeta personal y en la carpeta de documentos después de ejecutar el servidor |
Una wiki puede describir una versión antigua. La wiki de Terraria menciona un comando death. El servidor Terraria 1.4.5.8 responde "Invalid command." a ese comando.
3. Examinar los archivos reales
Si puede descargar el servidor, examine usted mismo los archivos.
- Muestre todas las entradas del archivo comprimido. Compruebe si hay una carpeta por sistema operativo y si el mismo nombre de ejecutable aparece en más de una carpeta. El archivo de Terraria tiene
TerrariaServer.exeen la carpetaLinux/y en la carpetaWindows/. - Lea los archivos predeterminados byte a byte. Identifique la codificación (UTF-8, BOM, cp1252), los finales de línea (LF, CRLF), las claves de ejemplo comentadas y las líneas que no son comentarios.
- Añada las claves de ejemplo comentadas a la lista de ajustes. Una línea que no es un comentario da el valor predeterminado.
4. Ejecutar el servidor real
Inicie el servidor como lo hace el daemon: conecte stdin y stdout mediante tuberías. Registre la salida original. Si su entorno solo puede ejecutar una versión del servidor para otro sistema operativo, ejecute esa versión. Los comandos, los mensajes y el guardado son iguales cuando el código del juego es el mismo.
Registre lo siguiente:
- La línea de listo, la línea después del comando de parada y el tiempo que tarda un guardado.
- La salida de
help. Envíe cada comando que solo menciona un documento y anote la respuesta. - El indicador de la consola. Algunos servidores lo escriben sin salto de línea, y la línea siguiente empieza con el indicador. Terraria escribe
: Server started. - La respuesta a un comando enviado por la tubería. Si el servidor no responde, pruebe de nuevo con una pseudoconsola (sección 7).
- Los mensajes de listo y parada en cada idioma del servidor.
- Los archivos que crea el servidor al iniciar y al guardar. Terraria crea
world.wld.bakyworld.wld.bak2.
Algunos elementos necesitan un cliente del juego, por ejemplo los mensajes de entrada y un objetivo para expulsar. Deje esos elementos vacíos y escriba "no medido".
5. Requisitos de ejecución: portables y fijos
Algunos servidores necesitan un entorno de ejecución que la descarga no incluye, por ejemplo Java, XNA Framework o el entorno de Visual C++. No use un entorno instalado en el PC. Su versión puede ser distinta en cada PC.
Siga este procedimiento:
- Escriba la dirección, el tamaño, la firma y el SHA-256 del archivo oficial en la tabla de investigación.
- Encuentre el conjunto mínimo de archivos que necesita el servidor. Inicie el servidor solo con esos archivos para confirmarlo. Para Terraria son los cuatro ensamblados de XNA (
Microsoft.Xna.Framework,.Game,.Graphics,.Xact),XnaNative.dll,msvcr100.dllymsvcp100.dll. - En
install_server, descargue la versión fija. Compare el archivo con la suma oficial. Si no la hay, compárelo con un SHA-256 que haya registrado de un archivo con una firma de editor válida. - Coloque solo los archivos necesarios en la carpeta del servidor o de la instancia. Inicie el servidor con esa ruta.
- En
validate, busque esos archivos. Si falta alguno, devuelva un problema conseverity: "critical"y uncodepropio. Pida al usuario que vuelva a instalar el servidor.
No use derechos de administrador, una instalación en todo el sistema ni un servicio de Windows.
Límite: .NET Framework carga primero un ensamblado desde la caché global de ensamblados (GAC) cuando allí hay el mismo nombre y versión. Las DLL nativas se cargan primero desde la carpeta del servidor.
6. El aislamiento
En Windows, un módulo que no viene del catálogo firmado de Saba-chan se ejecuta en un AppContainer de Windows. Todo módulo nuevo se ejecuta en este aislamiento. Pruebe su módulo en el aislamiento antes de abrir un pull request.
El aislamiento bloquea lo siguiente:
| Bloqueado | Use en su lugar |
|---|---|
| Conexiones de loopback (la API del daemon, la API REST del servidor del juego) | daemon_stdin_command, daemon_rest, loopback_http, loopback_exchange. El daemon reenvía la solicitud |
Windows Installer (msiexec falla con el error 1601) y otros servicios | Lea el archivo de instalación (MSI, CAB) con Python |
Una carpeta que tempfile.mkdtemp crea en la carpeta de instancia | tempfile.mkstemp, o una carpeta creada con os.mkdir. Desde Python 3.13, mkdtemp da acceso solo al usuario actual, y la cuenta aislada no puede escribir en esa carpeta |
| Escrituras fuera de las carpetas permitidas | Las carpetas de instancia, de trabajo y de instalación, y las carpetas de data_roots |
Si una utilidad compartida falla en el aislamiento, no evite el fallo en el módulo. Informe del fallo como un problema del daemon.
7. Modos de consola
De forma predeterminada, el daemon conecta stdin y stdout del servidor mediante tuberías ([launch] console = "pipe"). Algunos servidores funcionan de otra manera cuando stdin es una tubería:
- Palworld retiene su salida hasta que se detiene.
- El servidor de Terraria para Windows no lee la entrada de una tubería. No respondió a los comandos ni a
exit. El daemon lo detuvo a la fuerza tras 60 segundos, sin guardar.
Para estos servidores, configure [launch] console = "pty". El daemon inicia entonces el servidor en una pseudoconsola (Windows ConPTY, pty de Unix).
Una pseudoconsola muestra cada comando enviado. Los saltos de línea también pueden cambiar. En una pseudoconsola, Terraria escribe el indicador : y Server started en líneas distintas. Escriba sus patrones para ambos casos.
8. Patrones de consola
Escriba los patrones de listo, entrada, salida y parada solo a partir de salida medida.
- Ponga los patrones de listo, entrada y salida en
[extensions.saba-core](ready_patterns,player_join_patterns,player_leave_patterns). Ponga el patrón de parada en[detection] graceful_exit_patterns. - Ancle cada patrón al inicio y al final de la línea. Una línea de chat con las mismas palabras no debe coincidir, por ejemplo
<Server> Server started. - Si puede aparecer un indicador antes del mensaje, acéptelo con
^(?:<indicador>)?. - Si el ajuste de idioma del servidor traduce un mensaje, añada el mensaje medido para cada idioma. Si solo añade inglés, el daemon no ve el estado de listo de un servidor configurado en otro idioma.
- Añada una prueba. Las líneas medidas deben coincidir con y sin indicador. Una línea de chat no debe coincidir.
9. Instalación y archivos de ajustes
Instalación:
- Si el archivo comprimido tiene una carpeta por sistema operativo, elija la carpeta por el nombre del sistema operativo. No la elija por el nombre del ejecutable, por la longitud de la ruta ni por la primera entrada. Si no encuentra ninguna carpeta o encuentra más de una, devuelva un fallo.
- No reemplace ajustes ni mundos existentes. Extraiga el archivo de ajustes de ejemplo solo cuando no exista ningún archivo de ajustes.
- Verifique cada archivo descargado. Use la suma oficial de cada binario. Si no hay suma oficial, use HTTPS a un host oficial fijo, el CRC del archivo comprimido y la presencia del ejecutable esperado. Escriba "sin suma oficial" y la fuente en la tabla de investigación. No invente una suma ni use una de una fuente comunitaria.
Archivos de ajustes:
- Lea y escriba el archivo con la sintaxis oficial de su formato. Por ejemplo, los archivos
.propertiesde Java tienen los escapes\:y\=, y un\al final de una línea la continúa. - No suponga una codificación. Lea el archivo con su codificación real y vuelva a escribirlo con la misma codificación y los mismos finales de línea. El archivo
serverconfig.txtde Terraria para Windows usa cp1252 y tiene el byte 0x92 en un comentario. Un módulo que solo lee UTF-8 no puede iniciar este servidor, ni guardar ni importar sus ajustes. - Cambie solo las claves que cambiaron. Conserve las demás claves, los comentarios y el orden.
- Si no puede leer el archivo, no lo escriba. Un archivo que falta, uno que no se puede leer y uno que no se puede interpretar son tres casos distintos.
10. Pruebas
Las pruebas unitarias y el kit de conformidad se ejecutan sin aislamiento y con archivos de ejemplo. No encuentran problemas que solo aparecen con la descarga real, en el aislamiento, en un modo de consola o en Windows. Haga los tres niveles de pruebas.
10.1 Pruebas unitarias
- Escriba en
test_lifecycle.pyuna prueba para cada función antes de escribir la función. - Ejecute la prueba y asegúrese de que falla.
- Escriba la función.
- Ejecute estas comprobaciones:
saba-core module validate mygame
saba-core module audit mygame
pytest conformance --module path/to/mygame --shared-libs path/to/saba-chan/modules
10.2 Pruebas con el servidor real (antes de un pull request)
Después de la sección 4, llame a las funciones del módulo sobre una carpeta de servidor real.
- Ejecute
install_servercon la descarga real. Asegúrese de que en la carpeta solo están los archivos de este sistema operativo. - Inicie el servidor con el comando de
get_launch_command. Asegúrese de que el patrón de listo coincide. - Envíe cada plantilla de comando. Asegúrese de que el servidor la acepta.
- Envíe el comando de parada. Asegúrese de que el servidor guarda y se detiene.
- Compare las rutas de
backup_pathsyreset_servercon los archivos que creó el servidor.
10.3 Pruebas en un PC real
Use la instalación normal de Saba-chan en un PC con Windows. Un módulo nuevo se ejecuta en el aislamiento, así que esta prueba también encuentra problemas del aislamiento.
- Copie la carpeta del módulo en
modules\<nombre>\dentro de la carpeta de datos de Saba-chan. - Ejecute
saba-chan-cli module refresh. - Ejecute
saba-chan-cli server add <servidor> -m <módulo>. - Inicie el servidor. Asegúrese de que Saba-chan muestra el estado de listo.
- Envíe comandos con
saba-chan-cli run <servidor> <comando>. Lea las respuestas consaba-chan-cli server console <servidor> --print. - Cambie un ajuste y reinicie el servidor. Asegúrese de que el servidor usa el nuevo valor.
- Cree una copia con
saba-chan-cli backup create <servidor>. Examine los archivos de la copia. - Detenga el servidor. Asegúrese de que Saba-chan registra una parada normal y de que el mundo guardado sigue ahí.
- Restablezca el mundo. Examine qué archivos se borraron y cuáles se conservaron.
Si [module.dependencies] saba-core pide una versión que aún no se ha publicado, la instalación normal no carga el módulo. Haga la prueba en el PC cuando esa versión esté publicada. No baje la versión de la dependencia.
11. Lista de comprobación antes de un pull request
-
RESEARCH.mdtiene una fuente para cada elemento, y cada fuente indica "documento" o "medición". - Examinó las entradas del archivo comprimido y los bytes originales de los archivos predeterminados.
- Ejecutó el servidor real y registró la salida original, la salida de
helpy los archivos después de guardar. - Cada comando declarado está en la salida de
help. - El servidor responde a los comandos. Si no, está configurado
[launch] console = "pty". - Cada patrón de consola viene de salida medida y acepta el indicador y cada traducción.
- Cada entorno de ejecución es una versión portable fija, y el módulo verifica los archivos descargados.
- La instalación extrae solo la carpeta de este sistema operativo.
- El archivo de ajustes conserva su codificación y sus finales de línea.
- El restablecimiento del mundo borra solo archivos que creó el servidor, incluidas sus copias.
- El módulo no usa
msiexec, un servicio de Windows, una carpeta demkdtempni una conexión directa de loopback. - Hizo las pruebas con el servidor real y en un PC real, o anotó cada prueba que no pudo hacer.