Modding:Setting up your Development Environment/ru

Эта страница проверялась в последний раз для версии Vintage Story 1.18.8-rc.1.

Программное обеспечение

Когда вы будете готовы приступить к кодированию модов для Vintage Story, вы, вероятно, захотите настроить среду разработки, которая упростит процесс кодирования и тестирования ваших творений. Vintage Story разрабатывается на C# и начиная с версии 1.18.8 мы перешли на .NET 7.

Есть несколько приложений, которые помогут вам в разработке модов. Вот некоторые из них, поддерживающие наш шаблон:

• Visual Studio Community — это бесплатная и очень мощная среда разработки от Microsoft и, возможно, имеет наилучшую поддержу С# и .NET, которые в свою очередь тоже разработаны Microsoft. Это также инструмент, который команда Vintage Story использует при билде игры. Она также имеет MacOS версию. При использовании установите пакет .NET desktop development.

• Jetbrains Rider — это платная, мощная и удобная среда разработки специально спроектированная для .NET. Поскольку она создана для .NET, она также имеет очень хорошую поддержку всех функций, которые могут вам понадобиться, и при этом является полностью кроссплатформенной. Она также используется командой Vintage Story при разработке игры.

• Visual Studio Code — это бесплатный, лёгкий и универсальный редактор кода, разработанный Microsoft. Он поддерживает множество языков программирования и предлагает широкий выбор функциональных расширений. Расширение для поддержки C# — отличный выбор для начала создания модов. Этот редактор широко используется нашим сообществом мододелов.

Хоть вы и можете использовать любой редактор для работы с исходном кодом, мы настоятельно рекомендуем использовать один из вышеперечисленных инструментов, чтобы ваши процессы стали гораздо удобнее.

Выберите одну из вышеперечисленных IDE или другие альтернативы. Мы предлагаем использовать Visual Studio Community для Windows. Для Linux вы можете использовать Visual Studio Code или Rider.

Примечание: Если вы используете Linux и собираетесь ставить Visual Studio Code или Rider из Flatpak или snap? имейте в виду, что могут возникнуть некоторые проблемы с использованием .NET или переменных среды. Так что, по возможности используйте нативные методы установки.

Далее вам нужно будет установить .NET 7 SDK (Комплект для разработки программного обеспечения), который также будет включать .NET 7 Dekstop Runtime, необходимый для запуска игры начиная с версии 1.18.8-rc.1.

Убедитесь, что .NET 7 SDK установился правильно, выполнив следующую команду в терминале:

В Windows откройте приложение Windows PowerShell, которое предустановлено во всех современных версиях Windows (10 / 11).

dotnet --list-sdks

Она выведет список установленных SDK, одна из которых, должна иметь 7.0.xxx. Если это так, то можете продолжать.

Setup the Environment

Our Mod template makes use of the environment variable VINTAGE_STORY. Which we will set up to contain the path of where your game is installed. The use of the environment helps to keep the setup and the template simple so we recommend using it and will cover it in this article.

The VINTAGE_STORY Environment Variable simplifies reusing your Vintage Story game installation path and helps if multiple modders work on the same project to reference the VINTAGE_STORY Environment Variable and have their game installed where ever they want.

Windows

Here you have two options to set the environment variable:

• Use this short PowerShell script. Open the Windows PowerShell Application and paste the following into it and hit ENTER

[Environment]::SetEnvironmentVariable("VINTAGE_STORY", "$Env:AppData\Vintagestory", "User")

Change $Env:AppData\Vintagestory if you used a custom installation path for your game.

• Follow these manual steps to set the Environment variable

Search in Windows search for Edit the system environment variables > Environment Variables... > User variables for USER > New > Add insert the Variable name: VINTAGE_STORY and add the path to your Vintage Story installation.

For example, the default installation directory would be C:\Users\<Username>\AppData\Roaming\Vintagestory, (replace <Username> with your username) if you are not sure where yours is type %appdata% into the URL field in the File Explorer and hit ENTER. It will take you to your AppData\Roaming folder where Vintage Story should be installed if you haven't changed the default installation location.

Note: Do not confuse the AppData\Roaming\VintagestoryData directory with the AppData\Roaming\Vintagestory folder. The VintagestoryData directory only holds your Settings, Logs, Savegames and Mods.

Linux and Mac

To set an environment variable in Linux/Mac you need to add the following to your shells startup file:

export VINTAGE_STORY="$HOME/ApplicationData/vintagestory"

Replace the path with the one where your Vintagestory installation is located. The above path should point to your install when you installed Vintagestory using the install.sh script.

Run echo $SHELL in a terminal to see what shell you are using.

• For Bash place it in: ~/.bashrc or ~/.bash_profile at the end
• For Zsh place it in: ~/.zshrc or ~/.zprofile at the end
• If you use another shell see their documentation on how their shell startup file is called

Note: If you are using ~/.bash_profile or ~/.zprofile you will have to Logout and Login again to apply the changes. When using ~/.bashrc or ~/.zshrc you only need to restart the application that needs to use the environment variable (Visual Studio, Rider, Visual Studio Code, Terminal).

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

Mod Template package

The first and recommended option would be to use the template package.

Install the mod Mod template package using the following command on the Terminal:

dotnet new install VintageStory.Mod.Templates

This will download the latest mod template package from nuget.org

Once the template is installed you will see it inside Visual Studio and Rider. From there you can use the templates to create a new Project.

Visual Studio

We advise you to check the option Place solution and project in the same directory for Visual Studio This will flatten the project tree by one folder and make it easier to navigate.

If you don't want the log output to show up in a separate window you can check the option SuppressWindowsConsoleWindow. When enabled the log output will still be shown inside the Visual Studio Debug Output.

Open Visual Studio and click on Create a new project. If you installed the VintageStory.Mod.Templates you can then select Vintage Story Mod.

• 

  Visual Studio Mod Template

• 

  Visual Studio Mod Template setup

• 

  Visual Studio Mod Template options

Rider

We advise you to check the option Put solution and project in the same directory for Rider. This will flatten the project tree by one folder and make it easier to navigate.

Open Rider and click on New Solution. If you installed the VintageStory.Mod.Templates you can then select Vintage Story Mod.

Note: Unfortunately as of writing this Rider does not support those template options as Visual Studio in the UI yet but you can check this issue for updates. For now you can make use of those options using the CLI see the Visual Studio Code section for how to use it.

Visual Studio Code

To create a new Mod using the template when using Visual Studio Code you have to resort to using the command line for now since there is no UI that supports the options as well. Open a folder in Visual Studio Code where you want your mod to be. Then open the terminal within Visual Studio code Terminal > New Terminal.

• Create a new Mod Project with launch.json and task.json to easily start it and a Solution file. Other IDE's create that automatically so that is why we have this additional --AddSolutionFile flag for VS Code.

dotnet new vsmod --IncludeVSCode --AddSolutionFile

For all possible options run the following in the terminal:

dotnet new vsmod --help

Once you opened or created a template Visual Studio will prompt you to install the recommended extension, click on Show Recommendations and install the the pre-release version of the C# Dev Kit extension. This will also install the required C# automatically for you. These two extensions are recommended and will add Syntax highlighting, Autocomlet and many more much-needed features for writing C# code.

Other / Commandline

If want to use the Commandline you can use all template options on the Commandline in any Terminal Application with the help of the dotnet command.

• Create a new VS mod in the folder mytestmod in the current location of the terminal.

dotnet new vsmod --AddSolutionFile -o mytestmod

• or create a dll/code only mod

dotnet new vsmoddll --AddSolutionFile -o mytestmod

For all possible options run the following in the terminal:

dotnet new vsmod --help

When using the Commandline you can specify these options like so:

# Will create a new Mod Project with the dependency for VSSurvivalMod
dotnet new vsmod --AddSolutionFile --IncludeVSSurvivalMod -o mytestmod

---

Finally in mytestmod\mytestmod\modinfo.json change the name, modid , authors and description to describe your mod.

Обновление шаблонов

Чтобы обновить все установленные шаблоны, выполните команду:

dotnet new update

Но это не обязательно при создании нового мода, так как команда dotnet new vsmod установить новую версию шаблона, если она доступна.

Структура папок

Вот обзор того, где находятся файлы в вашем моде.

Название	Описание
mytestmod
.vscode	Если вы указали --IncludeVSCode, то эта папка будет содержать всё необходимое для запуска, упаковки и дебага вашего мода в Visual Studio Code.
CakeBuild	Этот проект содержит код, который билдит mytestmod_x.x.x.zip. Вы можете выполнить его, выбрав CakeBuild в Run Configuration.
mytestmod	Это ваш проект. Он содержит весь ваш код, ассеты и modinfo.json
assets	Ваши ассеты. Смотри Модинг:Система ассетов
modinfo.json	Описывает ваш мод. Автор, зависимости, название и многое другое. Смотри Модинфо
Properties
launchSettings.json	Здесь содержится информация о том, как запустить ваш мод (Visual Studio, Rider). Вы можете добавить пользовательские параметры запуска, чтобы, например, при старте запускаться прямо в мир. Запустите Vintagestory.exe -h, чтобы увидеть все параметры из терминала, открытого в папке Vintagestory.
mymod.csproj	csproj вашего мода. Содержит информацию о версии .NET и зависимостях (например, VintagestoryAPI).
Releases	Будет содержать релиз вашего мода после выполнения CakeBuild.
mytestmod	Файлы мода перед упаковкой в .zip архив.
mytestmod_x.x.x.zip	Готовый к релизу мод в виде zip-архива.

Проект-шаблон мода

Use the Github Mod template to create a new mod

The Github Mod template provides an easy way to get the basics for mod setup so you can start directly with adding your modifications to the game.

• Without using git and Github account

To get a copy of the template click the <> Code button on the GitHub repository site. Then download the template as ZIP file and extract it.

• Using Github and or git command

You can directly click on Use this template on the GitHub repository site to create a copy of it to your GitHub account. After that, you can clone your new repository to your computer.

If you do not use GitHub just clone the repo and upload it to your preferred Git hosting provider (Gitlab, BitBucket, ...)

With a local copy of the template, you can go ahead and open the ModTemplate.sln either in Visual Studio, Rider or Open the folder in Visual Studio Code. The Template is ready to use for any of the aforementioned IDE's. Now you can already start the mod with the game.

When opened you need to change the following to release the mod since a mod has to have a unique modid for the VSModDB:

In modtemplate\resources\modinfo.json change the name, modid , authors and description to describe your mod.

For a full list of available options see Modinfo.

The modid has to contain only lowercase letters and numbers. No special chars, whitespaces, uppercase letters, etc. are allowed.

Next, rename the folder modtemplate\resources\assets\mymodid to match what your modid is.

Finally change in the file modtemplate\modtemplateModSystem.cs the line

Lang.Get("mymodid:hello")

from mymodid to your new modid.

The file modtemplate\modtemplateModSystem.cs can be called whatever you like.

(Optional) Further, you can change the name ModTemplate to whatever you like as long as you change all of the following:

• Folder ModTemplate
• File ModTemplate\ModTemplate.csproj
• In File CakeBuild\Program.cs on line

ProjectName = "ModTemplate";

If you are on linux and used the Github Template make sure to update in ModTemplate\Properties\launchSettings.json the executablePath. There you need to remove the .exe

Запуск мода

Запуск мода в Visual Studio

Запуск мода в Rider

• 

  Запуск мода в Rider (Новый UI)

• 

  Запуск мода в Rider

Запуск мода в Visual Studio Code

Если у вас возникли проблемы, вы можете узнать больше из проекта vsmodexamples

Упаковка мода

With the new template, we are using the Cake build system. This includes a second Project within the Solution in the template. In all supported IDE's you can select from the dropdown that you used to launch the mod the CakeBuild option and run it. When using Visual Studio Code you can also create a package by running the package task. For that got to Terminal > Run Task... and select package.

It will perform a JSON validation on your assets so they are at least parsable by Newtonsoft.Json and then build a Releases/mymodid_1.0.0.zip. The version is taken from the mymod/modinfo.json file.

Congratulations now you have your mod development environment set up and a ready-to-release mod package.

Note: Make sure you use your own unique modid else you won't be able to upload the mod to the VSModDB.

Дальнейшее продвижение

Если вам удалось настроить среду разработки и запустить Vintage Story через проект мода в вашей IDE, то пришло время приступить к работе над своим первым модом кода. На данный момент есть много вариантов, которые вы можете выбрать, поскольку моды кода могут изменить практически любой аспект игры. Тем не менее, лучше всего начать с блоков и элементов (поскольку к этому моменту вы уже должны быть знакомы с их созданием используя JSON-ы).

Перейдите на страницу Продвинутые блоки, чтобы создать свой первый продвинутый блок кода.

Или перейдите на страницу Продвинутые предметы ^en, чтобы создать свой первый продвинутый предмет кода.

Wondering where some links have gone?
The modding navbox is going through some changes! Check out Navigation Box Updates for more info and help finding specific pages.