Modding:Guía del Modder/Introducción

Creación de mods SMAPI

---

• Introducción
• Fundamentos del juego
• Prueba y solución de problemas
• Lanzamiento
• Referencias API

  APIs de SMAPI Básicas:

  • Estructura del Mod
  • Manifest
  • Eventos
  • Configuración
  • Cargar y editar contenido
  • Datos
  • Entrada
  • Registro
  • Reflection
  • Multijugador
  • Traducción
  • Utilidades

  APIs de SMAPI Avanzadas:

  • Paquetes de Contenido
  • Comandos de la consola de Mods
  • Integración de mods
  • Harmony

• Guías específicos

← Modding:Índice

¿Quieres crear mods SMAPI para Stardew Valley? ¡Esta guía es para ti! Para usar mods, consulte Modding: Guía del jugador. Para crear paquetes de Content Patcher, consulte Modding: Content Patcher.

Introducción

¿Qué es un mod SMAPI?

Un mod SMAPI utiliza la API de modificación SMAPI para ampliar la lógica del juego. El mod puede responder cuando algo sucede en el juego (como cuando un objeto se coloca en el mundo), ejecutar código periódicamente, cambiar los recursos y datos del juego, etc. Los mods de SMAPI se escriben en C# usando .NET Framework, y Stardew Valley usa XNA/MonoGame para la lógica del juego (dibujo a la pantalla, entrada del usuario, etc.).

¿Porqué los mods usan SMAPI?

¡SMAPI hace muchas cosas por ti! Por ejemplo, SMAPI podrá...

1. Cargar tus mods en el juego. Mods de código no son posibles sin utilizar SMAPI para cargarlos.
2. Proporciona referencias API y eventos que te permiten interactuar con el juego de formas que de otra manera no podrías. Existen referencias API simplificados para cambios de recursos o información en el juego, configuración de jugadores, traducción, reflexión, etc. Estas se cubren posteriormente en la guía.
3. Vuelve a escribir tu mod para compatibilidad entre plataformas cuando carga. Esto te permite escribir el código de tu mod sin preocupación sobre las distintas versiones del juego en Windows/Mac/Linux.
4. Vuelve a escribir tu mod para actualizarlo. SMAPI detecta y repara código dañado por una actualización del juego en casos comunes.
5. Intercepta errores. Si tu mod falla o causa un error, SMAPI interceptará el error, mostrará los detalles del error en la consola, y en la mayoría de los casos recuperará automáticamente el juego. Esto significa que tu mod no cerrará accidentalmente el juego, y hará mucho mas sencillo el proceso de reparar errores.
6. Proporciona chequeo de actualizaciones. SMAPI alertará automáticamente a los jugadores cuando una actualización de tu mod esté disponible.
7. Proporciona chequeo de compatibilidad. SMAPI automáticamente detecta cuando tu mod es incompatible, y lo cierra antes de que cause problemas, para que los jugadores no usen juegos con fallos.

¿Puedo yo hacer un mod?

¡Por supuesto! Esta guía te ayudará a crear un mod paso a paso. Si la sigues al pie de la letra, ¡Habrás creado un mod! Ahora solo tendrás que hacer que haga lo que tu desees.

Si eres nuevo programando: Muchos desarrolladores de mods empiezan con poca o nula experiencia en programación. Ciertamente puedes aprender en el camino si estás determinado, pero debes estar preparado para una curva de aprendizaje muy empinada. No seas muy ambicioso al principio; es mejor empezar con un mod pequeño mientras aprendes el proceso. Es muy fácil terminar abrumado y rendirse la primera vez. ¡La comunidad de mods es muy amistosa, así que no dudes en preguntar!

Si ya tienes experiencia en programación, no debería haber problema. Experiencia en C# o Java hará las cosas mas sencillas, pero no es algo crítico. Si no estás familiarizado con C#, puedes dar un repaso en las referencias Aprendiendo C# abajo para completar cualquier hueco.

¿Es posible hacer un mod sin SMAPI?

Sí. Muchos mods de SMAPI tienen soporte para 'paquetes de contenido', que te permiten proporcionar archivos de texto tipo JSON, imágenes, etc. que los utilizan. Por ejemplo, puedes usar Content Patcher para editar las imágenes del juego y información sin usar programación. El resto de la guía habla de como hacer un mod SMAPI; para paquetes de contenido, checa Modding:Content Patcher (o la documentación de otro mod si quieres hacer un paquete de contenido para otro mod).

¿Dónde puedo obtener ayuda?

La comunidad de mods de Stardew Valley es muy amigable. Siéntete libre de pedir ayuda en el canal de #modding en el servidor de Discord de Stardew Valley.

Primeros pasos

Aprender C#

Como los mods están escritos en C#, es una buena idea acostumbrarse a su uso primero. No es necesario memorizar todo, pero conocimiento de cosas básicas (como campos, métodos, variables, y clases) hará el resto mucho mas fácil.

Algunos recursos útiles:

• Introducción a C#
• Fundamentos de C# para absolutos principiantes (en inglés)

Requisitos

Antes de empezar:

1. Lee la Guía del Jugador. El resto de esta guía asume que ya estás familiarizado en el uso de mods.
2. Instala Stardew Valley.
3. Instala SMAPI.
4. Instala el IDE (entorno de desarrollo integrado).
   • En Linux: instala MonoDevelop.
   • En Mac: instala Visual Studio 2017 para Mac. (Esto es MonoDevelop con otra marca.)
   • En Windows: instala Visual Studio 2017 Community. Cuando el instalador pregunte sobre cargas de trabajo, selecciona Desarrollo del escritorio de .NET.

Si no estás familiarizado con Visual Studio 2017 (En Windows/Mac) o MonoDevelop (en Linux), Modding:IDE reference explica como hacer las cosas importantes que necesitas para esta guía.

Crear un mod básico

Inicio rápido

Si ya tienes suficiente experiencia para saltarte el tutorial, aquí hay un pequeño resumen de esta sección,

expande para pequeño resumen

Crea una Biblioteca de clases (.NET Standard) vacía. Utiliza .NET Framework 4.5, 4.5.1, o 4.5.2 para una mejor compatibilidad. Referencia el Pathoschild.Stardew.ModBuildConfig paquete NuGet para automaticamente añadir las referencias correctas según plataforma en la que estés creando el mod. Crea una clase ModEntry con subclases StardewModdingAPI.Mod. Elimina el método Entry, y escribe tu cóidgo usando eventos y referencias API de SMAPI. Crea un archivo manifest.json que describe tu mod de SMAPI. Crea un archivo zip que contenga la información del mod para publicarlo.

Crear el proyecto

Un mod SMAPI es una librería compilada (DLL) con un método de entrada invocado por SMAPI, así que veamos que es eso.

1. Abre Visual Studio 2017 o MonoDevelop.
2. Crea una solución usando una Biblioteca de clases (.NET Standard) (lee como crear un proyecto). Asegúrate de escoger .NET Framework, no .NET Core o .NET Standard.
3. Cambia la red de trabajo a .NET Framework 4.5, 4.5.1, o 4.5.2 para una mejor compatibilidad (lee como cambiar la red de trabajo).
4. Referencia el paquete NuGet Pathoschild.Stardew.ModBuildConfig (lee como añadir el paquete).
5. Reinicia Visual Studio/MonoDevelop tras instalar el paquete.

Añadir el código

Ahora hay que añadir algo de código, que SMAPI ejecutará.

1. Elimina el archivo Class1.cs o MyClass.cs (lee como eliminar un archivo).
2. Añade un archivo de clase C# llamado ModEntry.cs a tu proyecto (lee como añadir un archivo).
3. Pon este código en el archivo (reemplaza NombreDeTuProyecto con el nombre de tu proyecto):

   using System;
   using Microsoft.Xna.Framework;
   using StardewModdingAPI;
   using StardewModdingAPI.Events;
   using StardewModdingAPI.Utilities;
   using StardewValley;
   
   namespace NombreDeTuProyecto
   {
       /// <summary>El punto de entrada del mod.</summary>
       public class ModEntry : Mod
       {
           /*********
           ** Métodos públicos
           *********/
           /// <summary>El punto de entrada del mod, invocado cuando el mod se carga por primera vez.</summary>
           /// <param name="helper">Proporciona referencias API simplificadas al escribir mods.</param>
           public override void Entry(IModHelper helper)
           {
               helper.Events.Input.ButtonPressed += this.OnButtonPressed;
           }
   
   
           /*********
           ** Métodos privados
           *********/
           /// <summary>Invocado cuando el jugador presiona un boton en el teclado, controlador, o ratón</summary>
           /// <param name="sender">El invocador del objeto</param>
           /// <param name="e">La información del objeto</param>
           private void OnButtonPressed(object sender, ButtonPressedEventArgs e)
           {
               // ignora si el jugador aún no ha cargado una partida
               if (!Context.IsWorldReady)
                   return;
   
               // muestra los clicks del boton en la consola
               this.Monitor.Log($"{Game1.player.Name} presionó {e.Button}.", LogLevel.Debug);
           }
       }
   }
   

Un resumen de lo que el código está haciendo:

1. using X; (lee palabra clave using) permite utilizar clases disponibles en ese espacio de nombres en tu código.
2. namespace NombreDeTuProyecto (lee palabra clave namespace) Define el alcance del código de tu mod. No te preocupes de esto cuando apenas vayas empezando, Visual Studio o MonoDevelop lo añadirán automáticamente cuando crees un archivo.
3. public class ModEntry : Mod (lee palabra clave class) crea la clase principal del mod, y subclases tipo SMAPI Mod. SMAPI detectará las subclases de tu Mod automáticamente, y Mod te dará acceso a las referencias API de SMAPI.
4. public override void Entry(IModHelper helper) es el método que SMAPI invocará cuando tu juego sea cargado. El helper proporciona un conveniente acceso a las referencias API de SMAPI.
5. helper.Events.Input.ButtonPressed += this.OnButtonPressed; maneja un evento (en otras palabras, un método a invocar) cuando el evento de presionar un botón ocurre. En otras palabras, cuando un botón es presionado (el evento helper.Events.Input.ButtonPressed), SMAPI invocará tu método this.OnButtonPressed. Lee eventos en la referencia de SMAPI para mas información.

Añade tu manifest

El manifest del mod le da información a SMAPI sobre tu mod.

1. Añade un archivo llamado manifest.json a tu proyecto.
2. Pega este código en ese archivo:

   {
     "Name": "<el nombre de tu proyecto>",
     "Author": "<tu nombre>",
     "Version": "1.0.0",
     "Description": "<una o dos oraciones acerca de tu mod>",
     "UniqueID": "<tu nombre>.<el nombre de tu proyecto>",
     "EntryDll": "<el nombre de tu proyecto>.dll",
     "MinimumApiVersion": "2.10.0",
     "UpdateKeys": []
   }
   

3. Reemplaza todos los "<...>" con la información correcta. ¡No dejes ningún símbolo tipo <>!

Esto será listado en la consola cuando el juego sea ejecutado. Para mas información, lee los documentos manifest.

Prueba tu mod

1. Construye el proyecto.
   Si seguiste los pasos de crear el proyecto correctamente, esto añadirá automáticamente tu mod a la carpeta de Mods en el juego.
2. Corre el juego con SMAPI.

Hasta ahora, el mod solo mandará un mensaje a la consola cada vez que se presione una tecla en el juego.

Solución de problemas

Si el mod tutorial no funciona...

1. Revisa todos los pasos para asegurarte de no haberte saltado alguno.
2. Checa los mensajes de error, que podrían explicar porque algo no está funcionando:
   • En Visual Studio, da click en Construir > Reconstruir solución y checa el panel de Salida o la lista de Error.
   • En MonoDevelop, da click en Build > Rebuild All y espera hasta que esté listo. Después, da click en la barra de arriba "Build: XX errors, XX warnings", y checa las pestañas de XX Errors y Build Output.
3. Lee la guía de solución de problemas.
4. Si todo lo anterior falla, puedes pedir ayuda en el canal de #modding en el servidor de Discord de Stardew Valley.

Ve mas lejos

Referencias API de SMAPI

SMAPI proporciona una serie de referencias API que te permiten hacer mas cosas. Lee la referencia SMAPI para mas información.

Soporte entre plataformas

SMAPI ajustará tu mod automáticamente para que funcione en Linux, Mac, y Windows. Aún así, hay algunas cosas que debes tomar en cuenta para evitar problemas:

1. Usa el paquete de configuración entre plataformas para automáticamente colocar las referencias de tu proyecto. Esto hace la compatibilidad mas fácil y te permite compilar en cualquier plataforma. (Si seguiste la guía de arriba, ya deberías tener esto.)
2. Usa Path.Combine para crear los caminos de los archivos, no construyas los caminos directamente, pues puede no funcionar en algunas plataformas.

   // ✘ ¡No hagas esto! No funcionará en Linux o Mac.
   string path = Helper.DirectoryPath + "\assets\asset.xnb";
   
   // ✓ Esto está bien.
   string path = Path.Combine(Helper.DirectoryPath, "assets", "asset.xnb");
   

3. Usa Helper.DirectoryPath, no intentes determinar el camino del mod tu mismo.

   // ✘ ¡No hagas esto! No funcionará si SMAPI reescribe el montaje (Ejemplo: para actualizarlo o añadir compatibilidad).
   string modFolder = Assembly.GetCallingAssembly().Location;
   
   // ✓ Esto está bien.
   string modFolder = Helper.DirectoryPath;
   

Descompila el código del juego

Cuando empieces a trabajar con mods mas complejos, puede que necesites leer el código del juego para saber como funciona.

Para descompilar el código para que lo puedas leer (aunque no será completamente funcional, debido a limitaciones del descompilador):

• En Windows:
  1. Abre StardewValley.exe en dotPeek.
  2. Da click derecho en Stardew Valley y selecciona Export to Project. Acepta las opciones predeterminadas para crear un proyecto decompilado, que puedes abrir en Visual Studio.
• En Linux/Mac:
  1. Instala Visual Studio Code para tu sistema operativo.
  2. Obten el plugin ILSpy .NET Decompiler para VSCode.
  3. Abre Visual Studio Code Command Palette (Command+Shift+P) y después escribe ilspy para mostrar los dos comandos.
  4. El comando Decompile IL Assembly (pick file) te permite escoger un montaje utilizando el diálogo de selección de archivos. El diálogo también debería permitir escribir el camino completo. Navega hasta StardewValley.exe en tu carpeta de juego StardewValley.
  5. Si el archivo es un montaje .NET válido, una vista llamada ILSPY DECOMPILED MEMBERS es agregada a la vista de explorador. Esta permite seleccionar y abrir varios nodos, cuyo código descompilado de C# es mostrado en el editor.

Para desempaquetar los archivos de información o imágenes tipo XNB, lee Modding:Editing XNB files.