Modificações:Guia do Modder/Começando

“ “Ainda tenho muito trabalho a fazer” — Robin Tradução incompleta Este artigo ou seção não foi completamente traduzido para o português. Você está convidado a ajudar na sua construção editando-o Última edição por LokKol em 2024-02-20 23:14:48.

Creating SMAPI mods

---

• Começando
• Game fundamentals
• Teste e Solução de Problemas
• Release
• API reference

  Basic SMAPI APIs:

  • Mod structure
  • Manifest
  • Events
  • Configuration
  • Load & edit content
  • Data
  • Input
  • Logging
  • Reflection
  • Multiplayer
  • Translation
  • Update checks
  • Utilities

  Advanced SMAPI APIs:

  • Content packs
  • Mod console commands
  • Mod integrations
  • Harmony patching

• Specific guides

← Modificações:Índice

Você quer criar mods SMAPI para o Stardew Valley? Este guia é para você! Para instruções sobre usar mods, veja Modificações:Guia do Jogador.

Intro

O que é um mod SMAPI?

Um mod SMAPI usa a API de modificação SMAPI para estender a lógica do jogo. O mod pode responder quando algo acontece no jogo (como quando um objeto é colocado no mundo), executar código periodicamente (como uma vez por atualização), alterar os ativos e dados do jogo, etc. Mods SMAPI são escritos em C# usando o O .NET Framework e o Stardew Valley usam XNA / MonoGame para a lógica do jogo (desenho na tela, entrada do usuário, etc.).

Por que os mods usam SMAPI?

SMAPI faz muito por você! Por exemplo, o SMAPI irá ...

1. Carregue seu mod no jogo. Mods de código não são possíveis sem o SMAPI para carregá-los.
2. Forneça APIs e eventos que permitam interagir com o jogo de maneiras que você não conseguiria. Existem APIs simplificadas para alterações de ativos / dados do jogo, configuração do jogador, tradução, reflexão etc. Isso será abordado mais adiante neste guia.
3. Reescreva seu mod para compatibilidade de plataformas cruzadas quando estiver carregado. Isso permite que você escreva código mod sem se preocupar com as diferenças entre as versões Linux / Mac / Windows do jogo.
4. Reescreva seu mod para atualizá-lo. O SMAPI detecta e corrige o código mod quebrado por uma atualização do jogo em casos comuns.
5. Erros de interceptação. Se o seu mod travar ou causar um erro, o SMAPI irá interceptar o erro, mostrar os detalhes do erro na janela do console e, na maioria dos casos, recuperar o jogo automaticamente. Isso significa que seu mod não travará acidentalmente o jogo e facilita muito a solução de erros.
6. Forneça verificações de atualização. O SMAPI alerta automaticamente os jogadores quando uma nova versão do seu mod está disponível.
7. Forneça verificações de compatibilidade. O SMAPI detecta automaticamente quando o seu mod é incompatível e o desativa antes de causar problemas, para que os jogadores não fiquem com jogos quebrados.

Posso fazer um mod?

Sim! Este guia irá ajudá-lo a criar um mod simples, passo a passo. Se você seguir em frente, você terá criado um mod! Então você só precisa fazer o que quiser.

Se você é iniciante em programação: muitos desenvolvedores de mod começam com pouca ou nenhuma experiência em programação. Você certamente pode aprender ao longo do caminho, se estiver determinado, mas deve estar preparado para uma curva de aprendizado acentuada. Não seja muito ambicioso a princípio; é melhor começar com um mod pequeno quando você descobrir isso. É fácil ficar impressionado no começo e desistir. A comunidade modding é muito acolhedora, portanto, não tenha medo de fazer perguntas!

Se você já tem experiência em programação, deve ficar bem. A experiência de programação em C# ou Java facilitará as coisas, mas não é crítica. Se você não está familiarizado com o C#, pode percorrer as referências abaixo de Learning C# para preencher as lacunas.

Posso fazer um mod sem SMAPI?

Sim. Muitos mods SMAPI suportam 'pacotes de conteúdo', que permitem fornecer arquivos de texto JSON, imagens etc. que eles usam. Por exemplo, você pode usar o Content Patcher para editar as imagens e os dados do jogo sem necessidade de programação. O restante deste guia é sobre como criar um novo mod SMAPI; para pacotes de conteúdo, consulte a documentação do mod que o lerá.

Onde posso obter ajuda?

A comunidade de modificação de Stardew Valley é muito acolhedora. Sinta-se livre para pedir ajuda em modding na Stardew Valley Discord.

Introdução

Aprenda C#

Como os mods são escritos em C#, é uma boa idéia familiarizá-lo primeiro. Você não precisa memorizar tudo, mas uma compreensão do básico (como campos, métodos, variáveis ​​e classes) facilitará todo o resto.

Alguns recursos úteis:

• C# Quickstarts ensina o básico do C# com exemplos interativos.
• Fundamentos de C# para iniciantes absolutos é um guia em vídeo que o orientará C#, dos conceitos básicos à programação orientada a eventos (que é o que os mods SMAPI usam principalmente).

Requisitos

Antes que você comece:

1. Leia o Player Guide. O restante deste guia pressupõe que você já esteja familiarizado com o uso de mods.
2. Instale o Stardew Valley.
3. Instale SMAPI.
4. Instale o IDE (ambiente de desenvolvimento integrado).
5. * No Linux: instale MonoDevelop.
6. * No Mac: instale Visual Studio para Mac. (Este é um MonoDevelop renomeado.)
7. * No Windows: instale Visual Studio Comumnity. Quando o instalador perguntar sobre cargas de trabalho, ative .NET Desktop Development .

Se você não está familiarizado com o Visual Studio (no Windows / Mac) ou o MonoDevelop (no Linux), Modding:IDE reference explica como fazer as coisas importantes necessárias para este guia.

Crie um mod básico

Inicio rápido

Se você tiver experiência suficiente para pular o tutorial, aqui está um rápido resumo desta seção:

Expanda para começo rápido

Crie uma biblioteca de classes vazia em um projeto com o C#. (não selecione o Biblioteca de Classes(.NET Framework)) Instâncie o .NET 5. Referencie o Pathoschild.Stardew.ModBuildConfig NuGet package para adicionar automaticamente as referências corretas, dependendo da plataforma em que o mod está sendo compilado. Crie uma classe com o nome ModEntry com uma subclasse chamada StardewModdingAPI.Mod. Reescreva o método Entry, e escreva seu código usando SMAPI events and APIs. Crie um manifest.json que descreva o seu mod para o SMAPI. Crie um arquivo zip contendo os arquivos do seu mod para o lançamento.

Crie o projeto

Um mod SMAPI é uma biblioteca compilada (DLL) com um método de entrada que é chamado por SMAPI, então vamos configurar isso.

1. Abra o Visual Studio 2022 ou MonoDevelop.
2. Crie uma solução com projeto de biblioteca de classes (veja como criar um projeto). (Não escolha Biblioteca de Classes .NET Framework!)
3. Mude a versão framework para .NET 5 (veja como alterar a versão do framework). Talvez você precise instalar o SDK
4. Referêncie Pathoschild.Stardew.ModBuildConfig NuGet package (veja como adicionar o pacote).
   • Se você estiver recebendo um erro informando que o tipo ou nome do namespace "StardewModdingAPI" não foi encontrado, é possível que o caminho do jogo não esteja sendo detectado. Você precisará definir a propriedade GamePath para o diretório executável do jogo. Isso pode ser feito adicionando uma propriedade GamePath ao PropertyGroup em suas configurações .csproj.
5. Reinicie o Visual Studio/MonoDevelop após a instalação do pacote.

Adicione o código

A seguir, vamos adicionar alguns códigos que o SMAPI executará.

1. Exclua o arquivo Class1.cs ou MyClass.cs (Veja como excluir um arquivo).
2. Adicione um arquivo C# class Chamado ModEntry.cs ao seu projeto (Veja como adicionar um arquivo).
3. Coloque este código no arquivo (substitua o YourProjectName pelo nome do seu projeto):

   using System;
   using Microsoft.Xna.Framework;
   using StardewModdingAPI;
   using StardewModdingAPI.Events;
   using StardewModdingAPI.Utilities;
   using StardewValley;
   
   namespace YourProjectName
   {
       /// <summary>O ponto de entrada do mod.</summary>
       public class ModEntry : Mod
       {
           /*********
           ** Métodos públicos
           *********/
           /// <summary>O ponto de entrada do mod, chamado após o mod ser carregado pela primeira vez.</summary>
           /// <param name="helper">Fornece APIs simplificadas para escrever mods</param>
           public override void Entry(IModHelper helper)
           {
               helper.Events.Input.ButtonPressed += this.OnButtonPressed;
           }
   
   
           /*********
           ** Métodos privados
           *********/
           /// <summary>Chamado após o jogador pressionar um botão no teclado, controle ou mouse.</summary>
           /// <param name="sender">O remetente do evento.</param>
           /// <param name="e">Os dados do evento.</param>
           private void OnButtonPressed(object sender, ButtonPressedEventArgs e)
           {
               // ignore se o jogador não tiver carregado o salvamento ainda.
               if (!Context.IsWorldReady)
                   return;
   
               // imprima o botão pressionado na janela do console.
               this.Monitor.Log($"{Game1.player.Name} apertou o botão {e.Button}.");
           }
       }
   }
   

Aqui um detalhamento do que o código faz:

1. using X; (veja using directive) torna as classes desse namespace disponiveis no seu código.
2. namespace YourProjectName (see namespace keyword) define o escopo do código do seu mod. Não se preocupe com isso quando estiver começando, o Visual Studio ou o MonoDevelop vai adiciona-lo automaticamente quando você adicionar um arquivo.
3. public class ModEntry : Mod (veja class keyword) cria a classe principal do seu mod, e subclasses da classe Mod do SMAPI. O SMAPI vai detectar as subclasses do Mod automaticamente, e o Mod lhe dará acesso as APIs do SMAPI.
4. public override void Entry(IModHelper helper) é o método que o SMAPI irá chamar ao seu mod ser carregado no jogo. O helper fornece acesso conveniente à várias APIs do SMAPI.
5. helper.Events.Input.ButtonPressed += this.OnButtonPressed; adiciona um 'manipulador de eventos' (i.e., um método para chamar) quando o evento do button-pressed (botão pressionado) ocorrer. Em outras palavras, quando um botão é pressionado (O evento helper.Events.Input.ButtonPressed), O SMAPI vai chamar o seu método this.OnButtonPressed. Veja events in the SMAPI reference para mais informações.

Adicionando seu manifest

O manifest conta ao SMAPI sobre seu mod.

1. Adicione um arquivo chamado manifest.json ao seu projeto.
2. Cole esse código dentro do arquivo (substituindo os <...> pelas informações):

   {
      "Name": "<nome do seu projeto>",
      "Author": "<seu nome>",
      "Version": "1.0.0",
      "Description": "<Uma ou duas frases sobre seu mod>",
      "UniqueID": "<seu nome>.<nome do seu projeto>",
      "EntryDll": "<nome do seu projeto>.dll",
      "MinimumApiVersion": "2.9",
      "UpdateKeys": []
   }
   

Isso será listado na saída do console quando o jogo for iniciado. Para obter mais informações, consulte a documentação do manifest.

Experimente o seu mod

1. Compile o projeto. (Para compilar o projeto: Visual Studio - Compilação > Compilar [Nome do seu projeto])
   Se você executou as etapas crie o projeto corretamente, isso adicionará automaticamente seu mod aos Mods do jogo.
2. Execute o jogo através do SMAPI.

O mod até agora enviará uma mensagem para a janela do console sempre que você pressionar uma tecla no jogo.

Solucionar problemas

Se o mod tutorial não funcionar ...

1. Revise as etapas acima para garantir que você não pulou alguma coisa.
2. Verifique as mensagens de erro que podem explicar por que não está funcionando:
3. * No Visual Studio, clique em Build > Rebuild Solution e verifique o painel Output ou a lista Error.
4. * No MonoDevelop, clique em Build > Rebuild All e aguarde até que esteja pronto. Em seguida, clique na barra "Build: XX errors, XX warnings" na parte superior e verifique as guias XX Errors e Build Output.
5. Consulte o Guia do Modder/Guia de Teste e Solução de Problemas.
6. Se tudo mais falhar, peça ajuda na #modding na Stardew Valley Discord. :)

Vá além

APIs do SMAPI

O SMAPI fornece um conjunto de APIs na qual você pode usar para criar mais. veja a referencia SMAPI para mais informações.

Suporte multiplataforma

O SMAPI irá ajustar automaticamente seu mod para funcionar no Linux, Mac e Windows. Entretanto, há alguma coisas que você deveria fazer para evitar problemas:

1. Use o pacote configuração de compilação multiplataforma para ajustar as referencias do seu projeto automaticamente. Isso facilita a compatibilidade entre plataformas, além de deixar seu código compilar em qualquer plataforma. (Se você tiver seguido o guia acima, já tem isso.)
2. Use Path.Combine para criar caminhos de arquivo, não codifique os separadores de caminho, pois poderão não funcionar em todas as plataformas.

// ✘ Não faça isso! Do contrario irá crashar (travar) no Linux/Mac.
string path = Helper.DirectoryPath + "\assets\asset.xnb";

// ✓ Isso é OK
string path = Path.Combine(Helper.DirectoryPath, "assets", "asset.xnb");

3. Use o Helper.DirectoryPath, Não tente determinar o caminho do mod sozinho.

   // ✘ Não faça isso! Ele vai crashar (travar) se o SMAPI reescrever o assembly. (''exp.'' para atualiza-lo ou torna-lo multiplataforma).
   string modFolder = Assembly.GetCallingAssembly().Location;
   
   // ✓ Isso é OK
   string modFolder = Helper.DirectoryPath;
   

Decompile o código do jogo

Quando você começar a trabalhar em mod mais complexos, você pode precisar olhar como o código do jogo funciona.

Para descompilar o código do jogo de modo que você possa lê-lo (embora não seja totalmente funcional devido à limitações do descompilador):

• No Windows:
  1. Abra o StardewValley.exe no dotPeek.
  2. Clique com o botão direito em Stardew Valley e escolha Export to Project. Aceite as opções padrões para criar um projeto decompilado que você poderá abrir no Visual Studio.
• No Linux/Mac:
  1. Abra o StardewValley.exe no MonoDevelop por meio do File > Open.
  2. Altere a Language do Summary para C#.

Para descompactar os arquivos XNB de dados/imagem, veja Modding:Editing XNB files.

Teste e solução de problemas →