Модификации:Моддер гайд/Приступая к работе: различия между версиями

Версия 14:39, 6 марта 2023

Создание SMAPI модов

Приступая к работе
Основы игры
Test & troubleshoot
Релиз
Ссылки API
Основы SMAPI API:
Advanced SMAPI APIs:
Specific guides

“	“Предстоит ещё много работы...”
	— Робин

Неполный перевод

Эта статья или её часть до сих пор не переведены на русский язык. Вы можете оказать помощь в переводе путем ее редактирования.
Последний раз редактировалось Максим в 2023-03-06 14:39:34.

Желаете начать создавать моды для игры Stardew Valley с помощью SMAPI? Тогда этот гайд для вас! Для использования модов, перейди в Modding:Player Guide. Для создания патчей, см Модификации:Content Patcher.

Вступление

Что за SMAPI?

SMAPI — это специальное API для создания модификаций с целью расширения логик игры. Мод поможет реализовать изменения в игре (например, добавить новый предмет в мир), периодично запускать строчки кода (например, добавить автоматическую проверку обновлений), изменять игровые механики, логики и другое. Модификации SMAPI написаны на языке программирования C#, используют технологию .NET Framework. Stardew Valley использует движок XNA/MonoGame для реализации игровых механик (отрисовка объектов, отслеживание пользовательского ввода и прочее).

Почему модификации используют SMAPI?

SMAPI предоставляет возможность для реализации многих функций. Например:

Загрузка мода в игру. Без SMAPI модификации не запустятся.
Упрощённые API, которые позволяют создать взаимодействия, которые раньше были недоступны. Они делают более простое внесение изменений в механики игры, настройку игрового персонажа, перевода и прочего. Но об этом чуть позже.
Кроссплатформенность. Это значит, что не нужно думать, как интегрировать модификацию на разные ОС.
Изменение и обновление модификации. SMAPI обнаруживает и чинит дыры в коде, приводящие к поломке игры.
Вывод ошибок. Если мод ломает игру или работает неправильно, SMAPI обнаружит ошибку, выведет её детали в окне консоли, и во многих случаях автоматически перезагрузит игру. Это значит, что поиск и устранение неполадки займёт гораздо меньше времени.
Система обновлений. SMAPI автоматически уведомляет игроков о выходе новой версии мода.
Проверка совместимости. SMAPI автоматически проверяет и определяет несовместимость или неработоспособность модификации на текущей системе и отключает его до появления проблем у игроков. Так пользователи не останутся со сломанными версиями игр.

Могу ли я создать мод?

Да! Этот гайд поможет вам создать простой мод пошагово. Если вы выполните все действия, то создадите основу мода! После этого вам будет нужно просто подстроить ее под свои нужды.

Если вы новичок в программировании, помните, многие создатели модов начинали с низким или нулевым уровнем программирования. Если вы решительно настроены, то точно можете научиться этому в процессе, но вы должны быть готовы приложить много усилий. Не будьте слишком амбициозно настроенными в самом начале, лучше начать с небольшого мода для пробы: иначе можно легко перегореть и бросить начатое. Сообщество по созданию модов очень дружелюбное, не бойтесь задавать вопросы!

Если же вы уже имели дело с программированием, то вы справитесь. Опыт в С# или Java облегчит задачу, но не критичен. Если вы не знакомы с С#, вы можете просмотреть приведенные ниже обучения по С# для закрытия некоторых пробелов.

Могу ли я создать мод без использования SMAPI?

Да. Многие SMAPI моды поддерживают так называемыe 'контент паки', которые позволят вам применять текстовые JSON файлы, изображения и т.п. Например, вы можете использовать Content Patcher для замены игровых картинок и данных без необходимости программировать. Оставшаяся часть этого гайда посвящена созданию SMAPI мода; для использования контент паков, прочитайте статью Modding:Content Patcher (или документацию мода, если вы создаете контент пак для другого мода).

Где я могу получить помощь?

Сообщество по созданию модов Stardew Valley очень дружелюбное. Не стесняйтесь просить о помощи в Discord сервере по модам Stardew Valley #making-mods.

Начало

Обучение C#

Так как моды пишутся на С#, хорошей идеей было бы ознакомиться с этим языком сразу. Вам не нужно запоминать все, но основы (вроде полей, методов, переменных и категорий) облегчат вам задачу.

Некоторые полезные ресурсы:

C# Quickstarts интерактивно обучает базам С#.
C# Fundamentals for Absolute Beginners - видеогайд, который проведет вас по С# от базовых концептов до событийно-ориентированного програмированния (в котором чаще всего моды SMAPI и нуждаются).

Требования

Прежде чем вы начнете:

Прочитайте Player Guide. Оставшаяся часть данного гайда подразумевает, что вы уже знакомы с использованием модов.
Установите Stardew Valley.
Установите SMAPI.
Установите IDE (интегрированная среда разработки).
- На Linux: установите MonoDevelop.
- На Mac: установите Visual Studio for Mac. (Это обновленный MonoDevelop.)
- На Windows: установите Visual Studio Community. Когда установщик спросит о рабочей нагрузке (workloads), добавьте разрешение для .NET Desktop Development.

Если вы не знакомы с Visual Studio (на Windows/Mac) или MonoDevelop (на Linux), Modding:IDE референс объясняет, как сделать необходимые вещи для этого гайда.

Create a basic mod

Быстрый старт

Если у вас достаточно опыта, чтобы пропустить учебник, вот краткий обзор этого раздела:

расширения для быстрого старта

Create an empty C# class library project.
Target .NET Framework 4.5, 4.5.1, or 4.5.2 for best compatibility.
Reference the Pathoschild.Stardew.ModBuildConfig NuGet package to automatically add the right references depending on the platform the mod is being compiled on.
Create a ModEntry class which subclasses StardewModdingAPI.Mod.
Override the Entry method, and write your code using the SMAPI events and APIs.
Create a manifest.json file which describes your mod for SMAPI.
Create a zip file containing the mod files for release.

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.

Open Visual Studio or MonoDevelop.
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, .NET Standard, or .NET 5+).
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).
That's the version installed and used by the game. Newer versions may not be installed for players, and SMAPI may not be able to load them.
Reference the Pathoschild.Stardew.ModBuildConfig NuGet package (see how to add the package).
Restart Visual Studio/MonoDevelop after installing the package.

Add the code

Next let's add some code SMAPI will run.

Delete the Class1.cs or MyClass.cs file (see how to delete a file).
Add a C# class file called ModEntry.cs to your project (see how to add a file).

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}.", LogLevel.Debug);
        }
    }
}

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

using X; (see using directive) makes classes in that namespace available in your code.
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.
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.
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.
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.

Add a file named manifest.json to your project.

Paste this code into the file:

{
  "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": "3.0.0",
  "UpdateKeys": []
}

Replace the <...> placeholders with the correct info. Don't leave any <> symbols!

This will be listed in the console output when the game is launching. For more info, see the manifest docs.

Try your mod

Build the project.
If you did the create the project steps correctly, this will automatically add your mod to the game's Mods folder.
Run the game through SMAPI.

The mod so far will just send a message to the console window whenever you press a key in the game.

Troubleshoot

If the tutorial mod doesn't work...

Review the above steps to make sure you didn't skip something.
Check for error messages which may explain why it's not working:
- In Visual Studio, click Build > Rebuild Solution and check the Output pane or Error list.
- In MonoDevelop, click Build > Rebuild All and wait until it's done. Then click the "Build: XX errors, XX warnings" bar at the top, and check the XX Errors and Build Output tabs.
If one of the errors (not necessarily the first one) says the package can't find your game folder, see Visual Studio can't find the game/SMAPI/XNA DLLs.
See the troubleshooting guide.
If all else fails, come ask for help in the #making-mods in the Stardew Valley Discord. :)

FAQs

Где SMAPI документация?

Это всего лишь руководство по началу. Для просмотра документации смотри: SMAPI reference и topics listed on the index page.

Как сделать кросс-платформенный мод?

SMAPI автоматически настроит ваш мод таким образом, чтобы он работал в Linux, macOS и Windows. Однако есть несколько вещей, которые вы должны сделать, чтобы избежать проблем:

Используйте конфигурацию кросс-платформенной сборки для автоматической настройки ссылок. Это упрощает кросс-платформенную совместимость и позволяет вашему коду компилироваться на любой платформе. (If you followed the above guide, you already have this.)
Используйте System.IO.Path.Combine для построения путей к файлу, не кодируйте разделители путей, так как они не будут работать на всех платформах.
```
// ✘ Don't do this! It won't work on Linux/Mac.
string path = this.Helper.DirectoryPath + "\assets\image.png";

// ✓ This is OK
string path = Path.Combine(this.Helper.DirectoryPath, "assets", "image.png");
```

Use this.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 = this.Helper.DirectoryPath;

The following describes the upcoming SMAPI 3.13.0, and may change before release.

An asset name identifies an asset you can load through a content API like Game1.content.Load<T>("asset name"), like Characters/Abigail. This is not a file path, and the asset name format on Windows does not match the path format. When comparing asset names, make sure you use PathUtilities.NormalizePath("some/path") instead of path helpers.

How do I decompile the game code?

It's often useful to see how the game code works. The game code is compiled into StardewValley.exe (i.e., converted to a machine-readable format), but you can decompile it get a mostly-readable approximation of the original code. (This might not be fully functional due to decompiler limitations, but you'll be able to see what it's doing.)

To decompile the game code...

First-time setup:
1. Install the latest ILSpy release for Windows release (get the "ILSpy_binaries" file under assets). You can use Avalonia ILSpy for Linux and macOS.
2. Open ILSpy.
3. Click View > Options, scroll to the "Other" section at the bottom, and enable "Always qualify member references".
Open StardewValley.exe in ILSpy.
Right-click on Stardew Valley and choose Save Code to create a decompiled project you can open in Visual Studio.

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

@@ Строка 56: / Строка 56: @@
 ===Быстрый старт===
 Если у вас достаточно опыта, чтобы пропустить учебник, вот краткий обзор этого раздела:
-{{collapse|расширить для быстрого start|content=&#32;
+{{collapse|расширения для быстрого старта|content=&#32;
 # Create an empty C# class library project.
 # Target .NET Framework 4.5, 4.5.1, or 4.5.2 for best compatibility.