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

Fonte: Stardew Valley Wiki
Revisão em 16h03min de 12 de março de 2020 por Margotbean (discussão | contribs) (add translation blocked by spam filter, fixed several formatting errors)
Saltar para a navegação Saltar para a pesquisa
Robin building.png
“ “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 Margotbean em 2020-03-12 16:03:24.

Creating SMAPI mods SMAPI mascot.png

← 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:

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 2017 para Mac. (Este é um MonoDevelop renomeado.)
  7. * No Windows: instale Comunidade do Visual Studio 2017. Quando o instalador perguntar sobre cargas de trabalho, ative .NET Desktop Development .

Se você não está familiarizado com o Visual Studio 2017 (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 
  1. Crie uma classe vazia em um projeto com o C#.
  2. Instancie o .NET Framework 4.5, 4.5.1, ou 4.5.2 para melhor compatibilidade.
  3. Referencie o Pathoschild.Stardew.ModBuildConfig NuGet package para adicionar automaticamente as referências corretas, dependendo da plataforma em que o mod está sendo compilado.
  4. Crie uma classe com o nome ModEntry com uma subclasse chamada StardewModdingAPI.Mod.
  5. Reescreva o método Entry, e escreva seu código usando SMAPI events and APIs.
  6. Crie um manifest.json que descreva o seu mod para o SMAPI.
  7. Crie um arquivo zip contendo os arquivos do seu mod para o lançamento.

Create the project

A SMAPI mod is a compiled library (DLL) with an entry method that gets called by SMAPI, so let's set that up.

  1. Open Visual Studio 2017 or MonoDevelop.
  2. Create a solution with a .NET Framework class library project (see how to create a project). Make sure you choose .NET Framework, not .NET Core or .NET Standard.
  3. Change the target framework to .NET Framework 4.5, 4.5.1, or 4.5.2 for best compatibility (see how to change target framework).
  4. Reference the Pathoschild.Stardew.ModBuildConfig NuGet package (see how to add the package).
  5. Restart Visual Studio/MonoDevelop after installing the package.

Add the code

Next let's add some code SMAPI will run.

  1. Delete the Class1.cs or MyClass.cs file (see how to delete a file).
  2. Add a C# class file called ModEntry.cs to your project (see how to add a file).
  3. Put this code in the file (replace YourProjectName with the name of your project): 
    using System;
using Microsoft.Xna.Framework;
using StardewModdingAPI;
using StardewModdingAPI.Events;
using StardewModdingAPI.Utilities;
using StardewValley;

namespace YourProjectName
{
    /// <summary>The mod entry point.</summary>
    public class ModEntry : Mod
    {
        /*********
        ** Public methods
        *********/
        /// <summary>The mod entry point, called after the mod is first loaded.</summary>
        /// <param name="helper">Provides simplified APIs for writing mods.</param>
        public override void Entry(IModHelper helper)
        {
            helper.Events.Input.ButtonPressed += this.OnButtonPressed;
        }


        /*********
        ** Private methods
        *********/
        /// <summary>Raised after the player presses a button on the keyboard, controller, or mouse.</summary>
        /// <param name="sender">The event sender.</param>
        /// <param name="e">The event data.</param>
        private void OnButtonPressed(object sender, ButtonPressedEventArgs e)
        {
            // ignore if player hasn't loaded a save yet
            if (!Context.IsWorldReady)
                return;

            // print button presses to the console window
            this.Monitor.Log($"{Game1.player.Name} pressed {e.Button}.");
        }
    }
}

Here's a breakdown of what that code is doing:

  1. using X; (see using directive) makes classes in that namespace available in your code.
  2. namespace YourProjectName (see namespace keyword) defines the scope for your mod code. Don't worry about this when you're starting out, Visual Studio or MonoDevelop will add it automatically when you add a file.
  3. public class ModEntry : Mod (see class keyword) creates your mod's main class, and subclasses SMAPI's Mod class. SMAPI will detect your Mod subclass automatically, and Mod gives you access to SMAPI's APIs.
  4. public override void Entry(IModHelper helper) is the method SMAPI will call when your mod is loaded into the game. The helper provides convenient access to many of SMAPI's APIs.
  5. helper.Events.Input.ButtonPressed += this.OnButtonPressed; adds an 'event handler' (i.e. a method to call) when the button-pressed event happens. In other words, when a button is pressed (the helper.Events.Input.ButtonPressed event), SMAPI will call your this.OnButtonPressed method. See events in the SMAPI reference for more info.

Add your manifest

The mod manifest tells SMAPI about your mod.

  1. Add a file named manifest.json to your project.
  2. Paste this code into the file (replacing the <...> placeholders): 
    {
   "Name": "<your project name>",
   "Author": "<your name>",
   "Version": "1.0.0",
   "Description": "<One or two sentences about the mod>",
   "UniqueID": "<your name>.<your project name>",
   "EntryDll": "<your project name>.dll",
   "MinimumApiVersion": "2.9",
   "UpdateKeys": []
}

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

Experimente o seu mod

  1. Construa o 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. :)

Go further

SMAPI APIs

SMAPI provides a set of APIs you can use to do more. See SMAPI reference for more info.

Crossplatform support

SMAPI will automatically adjust your mod so it works on Linux, Mac, and Windows. However, there are a few things you should do to avoid problems:

  1. Use the crossplatform build config package to automatically set up your project references. This makes crossplatform compatibility easier and lets your code compile on any platform. (If you followed the above guide, you already have this.)
  2. Use Path.Combine to build file paths, don't hardcode path separators since they won't work on all platforms. 
    // ✘ Don't do this! It will crash on Linux/Mac.
string path = Helper.DirectoryPath + "\assets\asset.xnb";

// ✓ This is OK
string path = Path.Combine(Helper.DirectoryPath, "assets", "asset.xnb");
  3. Use Helper.DirectoryPath, don't try to determine the mod path yourself. 
    // ✘ Don't do this! It will crash if SMAPI rewrites the assembly (e.g. to update or crossplatform it).
string modFolder = Assembly.GetCallingAssembly().Location;

// ✓ This is OK
string modFolder = Helper.DirectoryPath;

Decompile the game code

When you start working on more complex mods, you may need to look at how the game code works.

To decompile the game code so you can read it (though it won't be fully functional due to decompiler limitations):

  • On Windows:
    1. Open StardewValley.exe in dotPeek.
    2. Right-click on Stardew Valley and choose Export to Project. Accept the default options to create a decompiled project you can open in Visual Studio.
  • On Linux/Mac:
    1. Open StardewValley.exe in MonoDevelop through File > Open.
    2. Change Language from Summary to C#.

To unpack the XNB data/image files, see Modding:Editing XNB files.

Obtida de "https://pt.stardewvalleywiki.com/mediawiki/index.php?title=Modificações:Guia_do_Modder/Começando&oldid=16222"