Modding:Setting up your Development Environment: Difference between revisions

From Vintage Story Wiki

Modding:Setting up your Development Environment (view source)

Revision as of 16:56, 27 March 2024

4,966 bytes added ,  7 months ago
m
Updated navbox to new code navbox.
(VS 2022 add .NET desktop dev, add mod packaging, updated cli commands, VSCode extensions)
m (Updated navbox to new code navbox.)
(10 intermediate revisions by 4 users not shown)
Line 1: Line 1:
<languages/><translate>
<languages/>
<!--T:1-->
{{GameVersion|1.19.3}}
{{GameVersion|1.18.8-rc.1}}
<translate>
 
__FORCETOC__
__FORCETOC__
== Software == <!--T:2-->
== Software == <!--T:2-->
Line 10: Line 9:
VintageStory is developed in C# and since version 1.18.8 we switched to .NET 7.
VintageStory is developed in C# and since version 1.18.8 we switched to .NET 7.


<!--T:101-->
There are several applications that aid you in the development of mods and the following Software is supported by our modding template:
There are several applications that aid you in the development of mods and the following Software is supported by our modding template:


<!--T:4-->
<!--T:4-->
* [https://www.visualstudio.com/en/vs/community/ Visual Studio Community] is a free and very powerful development environment made by Microsoft and has probably the best support for working with C# and dotnet which are also developed by Microsoft. This is also the tool the Vintage Story Team uses to build the game. It also has a [https://www.visualstudio.com/vs/mac/ MacOS Version]. When using it make sure to install the <code>.NET desktop development</code> Workload as well.
* [https://www.visualstudio.com/en/vs/community/ Visual Studio Community] is a free and very powerful development environment made by Microsoft and has probably the best support for working with C# and dotnet which are also developed by Microsoft. This is also the tool the ''Vintage Story'' Team uses to build the game. It also has a [https://www.visualstudio.com/vs/mac/ MacOS Version]. When using it make sure to install the <code>.NET desktop development</code> Workload as well.


<!--T:88-->
<!--T:88-->
Line 21: Line 21:
* [https://code.visualstudio.com/ Visual Studio Code] is a free, lightweight and versatile source code editor developed by Microsoft. It supports numerous programming languages and offers a wide range of extensions to enhance its functionality. There are extensions to support C# and thus can be a good choice to start out making mods. It is a lot used by our modding community.
* [https://code.visualstudio.com/ Visual Studio Code] is a free, lightweight and versatile source code editor developed by Microsoft. It supports numerous programming languages and offers a wide range of extensions to enhance its functionality. There are extensions to support C# and thus can be a good choice to start out making mods. It is a lot used by our modding community.


<!--T:102-->
While you can use any text editor to edit source code files we highly recommend using any of the above tools to make your experience much more manageable.
While you can use any text editor to edit source code files we highly recommend using any of the above tools to make your experience much more manageable.


Line 26: Line 27:
Choose one of the above IDEs or other alternatives. We suggest using '''Visual Studio Community''' for Windows. For Linux you may want to use '''Visual Studio Code''' or '''Rider'''.
Choose one of the above IDEs or other alternatives. We suggest using '''Visual Studio Community''' for Windows. For Linux you may want to use '''Visual Studio Code''' or '''Rider'''.


<!--T:103-->
Note: If you are on Linux and plan to install Visual Studio Code or Rider using '''Flatpak''' or '''snap''' be aware that there might be some issues with using system tools like .NET 7 or the environment variables. So if possible please use a native installation method if possible.
Note: If you are on Linux and plan to install Visual Studio Code or Rider using '''Flatpak''' or '''snap''' be aware that there might be some issues with using system tools like .NET 7 or the environment variables. So if possible please use a native installation method if possible.




<!--T:104-->
Next, you will need to install the [https://dotnet.microsoft.com/en-us/download/dotnet/7.0 .NET 7 SDK] (Software Development Kit) this will also include the .NET 7 Dekstop Runtime which is needed to run the game since version 1.18.8-rc.1.
Next, you will need to install the [https://dotnet.microsoft.com/en-us/download/dotnet/7.0 .NET 7 SDK] (Software Development Kit) this will also include the .NET 7 Dekstop Runtime which is needed to run the game since version 1.18.8-rc.1.


<!--T:105-->
Verify that the .NET 7 SDK is correctly installed by running the following command in a Terminal:
Verify that the .NET 7 SDK is correctly installed by running the following command in a Terminal:


<!--T:106-->
''On Windows open the Application Windows PowerShell which is preinstalled on all modern Windows versions (10 / 11).''
''On Windows open the Application Windows PowerShell which is preinstalled on all modern Windows versions (10 / 11).''


<!--T:107-->
<syntaxhighlight lang=shell>
<syntaxhighlight lang=shell>
dotnet --list-sdks
dotnet --list-sdks
</syntaxhighlight>
</syntaxhighlight>


<!--T:108-->
It should return a list of installed SDK's and should contain a line with <code>7.0.xxx</code>. If that is the case you are good to continue.
It should return a list of installed SDK's and should contain a line with <code>7.0.xxx</code>. If that is the case you are good to continue.


== Setup the Environment ==
== Setup the Environment == <!--T:109-->
Our Mod template makes use of the environment variable <code>VINTAGE_STORY</code>. 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.
Our Mod template makes use of the <code>VINTAGE_STORY</code> ''environment variable''. An environment variable is a stored value within your operating system that can be easily accessed from any program. In this case, the <code>VINTAGE_STORY</code> variable allows our mod template to easily find our installation folder. The first step for setting up our environment is to create this environment variable to link to our game installation path.


The <code>VINTAGE_STORY</code> Environment Variable simplifies reusing your Vintage Story game installation path and helps if multiple modders work on the same project to reference the <code>VINTAGE_STORY</code> Environment Variable and have their game installed where ever they want.
<!--T:110-->
The <code>VINTAGE_STORY</code> environment variable simplifies reusing your Vintage Story game installation path and helps if multiple modders work on the same project to reference the <code>VINTAGE_STORY</code> Environment Variable and have their game installed where ever they want. As well as this, it increases the efficiency of updating any existing mods.


=== Windows ===
=== Windows === <!--T:111-->


<!--T:112-->
Here you have two options to set the environment variable:
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''
* Use this short PowerShell script. Open the ''Windows PowerShell'' Application, paste the following into it, and hit ''ENTER.''
<syntaxhighlight lang=shell>
<syntaxhighlight lang=shell>
[Environment]::SetEnvironmentVariable("VINTAGE_STORY", "$Env:AppData\Vintagestory", "User")
[Environment]::SetEnvironmentVariable("VINTAGE_STORY", "$Env:AppData\Vintagestory", "User")
</syntaxhighlight>
</syntaxhighlight>


<!--T:113-->
Change <code>$Env:AppData\Vintagestory</code> if you used a custom installation path for your game.
Change <code>$Env:AppData\Vintagestory</code> if you used a custom installation path for your game.


<!--T:114-->
* Follow these manual steps to set the Environment variable
* Follow these manual steps to set the Environment variable
Search in Windows search for <code>Edit the system environment variables</code> > <code>Environment Variables...</code> > User variables for USER > New > Add insert the Variable name: <code>VINTAGE_STORY</code> and add the path to your Vintage Story installation.
Search in Windows search for <code>Edit the system environment variables</code> > <code>Environment Variables...</code> > User variables for USER > New > Add insert the Variable name: <code>VINTAGE_STORY</code> and add the path to your Vintage Story installation.
[[File:Win env.png|400px|center|frameless|alt=Setup Windows environment variable]]
[[File:Win env.png|400px|center|frameless|alt=Setup Windows environment variable]]


<!--T:115-->
For example, the default installation directory would be <code>C:\Users\<Username>\AppData\Roaming\Vintagestory</code>, (replace <Username> with your username) if you are not sure where yours is type <code>%appdata%</code> 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.
For example, the default installation directory would be <code>C:\Users\<Username>\AppData\Roaming\Vintagestory</code>, (replace <Username> with your username) if you are not sure where yours is type <code>%appdata%</code> 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.


<!--T:116-->
[[File:Win appdata.png|400px|frameless|center|alt=find the default installation path of vintage story]]
[[File:Win appdata.png|400px|frameless|center|alt=find the default installation path of vintage story]]
Note:  
Note:  
Do not confuse the <code>AppData\Roaming\VintagestoryData</code> directory with the <code>AppData\Roaming\Vintagestory</code> folder. The <code>VintagestoryData</code> directory only holds your Settings, Logs, Savegames and Mods.
Do not confuse the <code>AppData\Roaming\VintagestoryData</code> directory with the <code>AppData\Roaming\Vintagestory</code> folder. The <code>VintagestoryData</code> directory only holds your Settings, Logs, Savegames and Mods.


=== Linux and Mac ===
=== Linux and Mac === <!--T:117-->
To set an environment variable in Linux/Mac you need to add the following to your shells startup file:
To set an environment variable in Linux/Mac you need to add the following to your shells startup file:


<!--T:118-->
<syntaxhighlight lang=shell>
<syntaxhighlight lang=shell>
export VINTAGE_STORY="$HOME/ApplicationData/vintagestory"
export VINTAGE_STORY="$HOME/ApplicationData/vintagestory"
Line 74: Line 88:
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.
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.


<!--T:119-->
Run <code>echo $SHELL</code> in a terminal to see what shell you are using.
Run <code>echo $SHELL</code> in a terminal to see what shell you are using.


<!--T:120-->
* For Bash place it in: <code>~/.bashrc</code> or <code>~/.bash_profile</code> at the end
* For Bash place it in: <code>~/.bashrc</code> or <code>~/.bash_profile</code> at the end
* For Zsh place it in: <code>~/.zshrc</code> or <code>~/.zprofile</code> at the end
* For Zsh place it in: <code>~/.zshrc</code> or <code>~/.zprofile</code> at the end
Line 81: Line 97:
Note: If you are using <code>~/.bash_profile</code> or <code>~/.zprofile</code> you will have to Logout and Login again to apply the changes. When using <code>~/.bashrc</code> or <code>~/.zshrc</code> you only need to restart the application that needs to use the environment variable (Visual Studio, Rider, Visual Studio Code, Terminal).
Note: If you are using <code>~/.bash_profile</code> or <code>~/.zprofile</code> you will have to Logout and Login again to apply the changes. When using <code>~/.bashrc</code> or <code>~/.zshrc</code> you only need to restart the application that needs to use the environment variable (Visual Studio, Rider, Visual Studio Code, Terminal).


== Setup a Mod  == <!--T:121-->


== Setup a Mod  ==
=== Mod Template package === <!--T:122-->
 
=== Mod Template package ===


<!--T:123-->
The first and recommended option would be to use the ''template package''.
The first and recommended option would be to use the ''template package''.


<!--T:124-->
Install the mod [https://github.com/anegostudios/VSdotnetModTemplates Mod template package] using the following command on the Terminal:
Install the mod [https://github.com/anegostudios/VSdotnetModTemplates Mod template package] using the following command on the Terminal:


<!--T:125-->
<syntaxhighlight lang=shell>
<syntaxhighlight lang=shell>
dotnet new install VintageStory.Mod.Templates
dotnet new install VintageStory.Mod.Templates
</syntaxhighlight>
</syntaxhighlight>


<!--T:126-->
This will download the latest mod template package from [https://www.nuget.org/packages/VintageStory.Mod.Templates nuget.org]
This will download the latest mod template package from [https://www.nuget.org/packages/VintageStory.Mod.Templates nuget.org]


<!--T:127-->
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.
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 ==== <!--T:128-->


==== Visual Studio ====
<!--T:129-->
 
We advise you to check the option  <code>Place solution and project in the same directory</code> for Visual Studio
We advise you to check the option  <code>Place solution and project in the same directory</code> for Visual Studio
This will flatten the project tree by one folder and make it easier to navigate.
This will flatten the project tree by one folder and make it easier to navigate.


<!--T:130-->
If you don't want the log output to show up in a separate window you can check the option <code>SuppressWindowsConsoleWindow</code>. When enabled the log output will still be shown inside the Visual Studio Debug Output.
If you don't want the log output to show up in a separate window you can check the option <code>SuppressWindowsConsoleWindow</code>. 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'''.
<!--T:131-->
<gallery mode="packed-hover" widths=400px heights=300px>
Open Visual Studio and click on ''Create a new project''. If you installed the ''VintageStory.Mod.Templates'' you can then select '''Vintage Story Mod'''. Your project name ''must'' be only lowercase letters for your mod to function correctly. It is recommended to enable the various include options in the setup.
<gallery mode="packed-hover" widths="400px" heights="300px">
File:Vs-cp-template.png|Visual Studio Mod Template
File:Vs-cp-template.png|Visual Studio Mod Template
File:Vs-cp-template-setup.png|Visual Studio Mod Template setup
File:Vs-cp-template-setup.png|Visual Studio Mod Template setup
Line 113: Line 135:
</gallery>
</gallery>


==== Rider ====
==== Rider ==== <!--T:132-->


<!--T:133-->
We advise you to check the option <code>Put solution and project in the same directory</code> for Rider.
We advise you to check the option <code>Put solution and project in the same directory</code> for Rider.
This will flatten the project tree by one folder and make it easier to navigate.
This will flatten the project tree by one folder and make it easier to navigate.


<!--T:134-->
Open Rider and click on ''New Solution''. If you installed the ''VintageStory.Mod.Templates'' you can then select '''Vintage Story Mod'''.
Open Rider and click on ''New Solution''. If you installed the ''VintageStory.Mod.Templates'' you can then select '''Vintage Story Mod'''.


<!--T:135-->
[[File:Rider-cp-template.png|400px|frameless|center|alt=Rider Mod Template|Rider Mod Template]]
[[File:Rider-cp-template.png|400px|frameless|center|alt=Rider Mod Template|Rider Mod Template]]




<!--T:136-->
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 [https://youtrack.jetbrains.com/issue/RIDER-16759/Support-parameters-in-custom-project-templates issue] for updates.
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 [https://youtrack.jetbrains.com/issue/RIDER-16759/Support-parameters-in-custom-project-templates 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.
For now you can make use of those options using the CLI see the  [[#Visual Studio Code|Visual Studio Code]] section for how to use it.


==== Visual Studio Code ====
==== Visual Studio Code ==== <!--T:137-->


<!--T:138-->
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.
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''.  
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''.  


<!--T:139-->
* 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 <code>--AddSolutionFile</code> flag for VS Code.''
* 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 <code>--AddSolutionFile</code> flag for VS Code.''
<syntaxhighlight lang=shell>
<syntaxhighlight lang=shell>
Line 136: Line 164:
</syntaxhighlight>
</syntaxhighlight>


<!--T:140-->
For all possible options run the following in the terminal:
For all possible options run the following in the terminal:
<syntaxhighlight lang=shell>
<syntaxhighlight lang=shell>
Line 141: Line 170:
</syntaxhighlight>
</syntaxhighlight>


<!--T:141-->
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 [https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit C# Dev Kit] extension. This will also install the required [https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csharp C#] automatically for you.
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 [https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit C# Dev Kit] extension. This will also install the required [https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csharp 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.
These two extensions are recommended and will add Syntax highlighting, Autocomlet and many more much-needed features for writing C# code.


==== Other / Commandline ====
==== Other / Commandline ==== <!--T:142-->
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.
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.


<!--T:143-->
* Create a new VS mod in the folder ''mytestmod'' in the current location of the terminal.
* Create a new VS mod in the folder ''mytestmod'' in the current location of the terminal.
<syntaxhighlight lang=shell>
<syntaxhighlight lang=shell>
Line 152: Line 183:
</syntaxhighlight>
</syntaxhighlight>


<!--T:144-->
* or create a dll/code only mod
* or create a dll/code only mod
<syntaxhighlight lang=shell>
<syntaxhighlight lang=shell>
Line 157: Line 189:
</syntaxhighlight>
</syntaxhighlight>


<!--T:145-->
For all possible options run the following in the terminal:
For all possible options run the following in the terminal:
<syntaxhighlight lang=shell>
<syntaxhighlight lang=shell>
Line 162: Line 195:
</syntaxhighlight>
</syntaxhighlight>


<!--T:146-->
When using the Commandline you can specify these options like so:
When using the Commandline you can specify these options like so:


<!--T:147-->
<syntaxhighlight lang=shell>
<syntaxhighlight lang=shell>
# Will create a new Mod Project with the dependency for VSSurvivalMod
# Will create a new Mod Project with the dependency for VSSurvivalMod
Line 169: Line 204:
</syntaxhighlight>
</syntaxhighlight>


<!--T:149-->
Finally in <code>mytestmod\mytestmod\modinfo.json</code>
change the <code>name</code>, <code>modid</code> , <code>authors</code> and <code>description</code> to describe your mod.


==== Updating the template package ====
==== Updating the template package ==== <!--T:150-->


<!--T:151-->
To update all installed templates you can run:
To update all installed templates you can run:
<syntaxhighlight lang=shell>
<syntaxhighlight lang=shell>
Line 177: Line 216:
</syntaxhighlight>
</syntaxhighlight>


<!--T:152-->
But this should not be necessary when creating a new mod, since using the <code>dotnet new vsmod</code> will check automatically if a new version of the template is available and install it.
But this should not be necessary when creating a new mod, since using the <code>dotnet new vsmod</code> will check automatically if a new version of the template is available and install it.


</br>
==== Folder structure ==== <!--T:153-->
Finally in <code>yourmod\resources\modinfo.json</code>
 
change the <code>name</code>, <code>modid</code> , <code>authors</code> and <code>description</code> to describe your mod.
<!--T:8-->
Here is an overview of where what files in your mod are located.
<table id="treeviewtable" class="table table-bordered tt-table" style='table-layout: fixed'>
  <tr style=''>
    <th width='300' align='left'>Name</th>
    <th width='600' align='left'>Description</th>
  </tr>
  <tr>
    <td><div class="tt" data-tt-id="root">mytestmod</div></td>
    <td></td>
  </tr>
  <tr>
    <td scope="row"><div class="tt" data-tt-id="p_vscode" data-tt-parent="root">.vscode</div></td>
    <td>If you checked --IncludeVSCode this folder will contain all stuff needed to run, package and debug your mod using Visual Studio Code.</td>
  </tr>
  <tr>
    <td scope="row"><div class="tt" data-tt-id="p_cakebuild" data-tt-parent="root">CakeBuild</div></td>
    <td>This Project contains the code that builds mytestmod_x.x.x.zip. You can execute it by selecting the Run Configuration CakeBuild.</td>
  </tr>
  <tr>
    <td scope="row"><div class="tt" data-tt-id="p_mytestmod" data-tt-parent="root">mytestmod</div></td>
    <td>This is your project. It contains all your code as well as the assets and the modinfo.json</td>
  </tr>
  <tr>
    <td scope="row"><div class="tt" data-tt-id="p_releases_assets" data-tt-parent="p_mytestmod">assets</div></td>
    <td>Contains your assets. See '''[[Modding:Asset System|Asset System]]'''</td>
  </tr>
  <tr>
    <td scope="row"><div class="tt" data-tt-id="p_releases_modinfo" data-tt-parent="p_mytestmod">modinfo.json</div></td>
    <td>Defines your mod. Author, Dependencies, Name and much more. See '''[[Modinfo | Modinfo]]'''</td>
  </tr>
  <tr>
    <td scope="row"><div class="tt" data-tt-id="p_releases_properties" data-tt-parent="p_mytestmod">Properties</div></td>
    <td></td>
  </tr>
  <tr>
    <td scope="row"><div class="tt" data-tt-id="p_releases_launchsettings" data-tt-parent="p_releases_properties">launchSettings.json</div></td>
    <td>This contains how to launch your mod (Visual Studio, Rider). You may want to add custom startup parameters to launch for example directly into a world when starting. Run Vintagestory.exe -h to see all options from a terminal opened in your Vintagestory install directory.</td>
  </tr>
  <tr>
    <td scope="row"><div class="tt" data-tt-id="p_releases_csproj" data-tt-parent="p_mytestmod">mymod.csproj</div></td>
    <td>Your mods csproj file. Contains information like the .NET version to build against and references to the VintagestoryAPI for example.</td>
  </tr>
  <tr>
    <td scope="row"><div class="tt" data-tt-id="p_releases" data-tt-parent="root">Releases</div></td>
    <td>Contains your mod release once the CakeBuild Run Configuration was run.</td>
  </tr>
  <tr>
    <td scope="row"><div class="tt" data-tt-id="p_releases_mymtestmod" data-tt-parent="p_releases">mytestmod</div></td>
    <td>Your mod files before getting packaged into a .zip file.</td>
  </tr>
  <tr>
    <td scope="row"><div class="tt" data-tt-id="p_releases_zip" data-tt-parent="p_releases">mytestmod_x.x.x.zip</div></td>
    <td>Ready to release mod zip.</td>
  </tr>


For a full list of available options see '''[[Modinfo | Modinfo]]'''.
<!--T:154-->
</table>


=== Template Mod Project ===
=== Template Mod Project === <!--T:155-->


<!--T:156-->
Use the [https://github.com/anegostudios/vsmodtemplate Github Mod template] to create a new mod
Use the [https://github.com/anegostudios/vsmodtemplate Github Mod template] to create a new mod




<!--T:157-->
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.
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.


<!--T:158-->
* Without using git and Github account
* Without using git and Github account


<!--T:159-->
To get a copy of the template click the <code><> Code</code> button on the GitHub repository site. Then download the template as ZIP file and extract it.  
To get a copy of the template click the <code><> Code</code> button on the GitHub repository site. Then download the template as ZIP file and extract it.  


<!--T:160-->
* Using Github and or git command
* Using Github and or git command


<!--T:161-->
You can directly click on <code>Use this template</code> on the GitHub repository site to create a copy of it to your GitHub account.
You can directly click on <code>Use this template</code> 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.
After that, you can clone your new repository to your computer.


<!--T:162-->
If you do not use GitHub just clone the repo and upload it to your preferred Git hosting provider (Gitlab, BitBucket, ...)
If you do not use GitHub just clone the repo and upload it to your preferred Git hosting provider (Gitlab, BitBucket, ...)


<!--T:163-->
<br>
<br>
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.
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.


<!--T:164-->
When opened you need to change the following to release the mod since a mod has to have a unique ''modid'' for the VSModDB:
When opened you need to change the following to release the mod since a mod has to have a unique ''modid'' for the VSModDB:
<br>
<br>


<!--T:165-->
In <code>modtemplate\resources\modinfo.json</code>
In <code>modtemplate\resources\modinfo.json</code>
change the <code>name</code>, <code>modid</code> , <code>authors</code> and <code>description</code> to describe your mod.
change the <code>name</code>, <code>modid</code> , <code>authors</code> and <code>description</code> to describe your mod.


<!--T:166-->
For a full list of available options see '''[[Modinfo | Modinfo]]'''.
For a full list of available options see '''[[Modinfo | Modinfo]]'''.


<!--T:167-->
The <code>modid</code> has to contain only lowercase letters and numbers. No special chars, whitespaces, uppercase letters, etc. are allowed.
The <code>modid</code> has to contain only lowercase letters and numbers. No special chars, whitespaces, uppercase letters, etc. are allowed.


<!--T:168-->
Next, rename the folder <code>modtemplate\resources\assets\mymodid</code> to match what your <code>modid</code> is.
Next, rename the folder <code>modtemplate\resources\assets\mymodid</code> to match what your <code>modid</code> is.


<!--T:169-->
Finally change in the file <code>modtemplate\modtemplateModSystem.cs</code> the line
Finally change in the file <code>modtemplate\modtemplateModSystem.cs</code> the line
<syntaxhighlight lang=cs>
<syntaxhighlight lang=cs>
Line 224: Line 333:
from <code>mymodid</code> to your new modid.
from <code>mymodid</code> to your new modid.


<!--T:170-->
The file <code>modtemplate\modtemplateModSystem.cs</code> can be called whatever you like.
The file <code>modtemplate\modtemplateModSystem.cs</code> can be called whatever you like.


<!--T:171-->
(Optional) Further, you can change the name <code>ModTemplate</code> to whatever you like as long as you change all of the following:
(Optional) Further, you can change the name <code>ModTemplate</code> to whatever you like as long as you change all of the following:
* Folder <code>ModTemplate</code>
* Folder <code>ModTemplate</code>
Line 234: Line 345:
</syntaxhighlight>
</syntaxhighlight>


<!--T:172-->
''If you are on linux and used the Github Template'' make sure to update in <code>ModTemplate\Properties\launchSettings.json</code> the <code>executablePath</code>. There you need to remove the <code>.exe</code>
''If you are on linux and used the Github Template'' make sure to update in <code>ModTemplate\Properties\launchSettings.json</code> the <code>executablePath</code>. There you need to remove the <code>.exe</code>


=== Launch the Mod ===
=== Launch the Mod === <!--T:173-->


==== Visual Studio Launch Mod ====
==== Visual Studio Launch Mod ==== <!--T:174-->
[[File:Vs-cp-start.png|600px|frameless|center|alt=Visual Studio Launch Mod|Visual Studio Launch Mod]]
[[File:Vs-cp-start.png|600px|frameless|center|alt=Visual Studio Launch Mod|Visual Studio Launch Mod]]


==== Rider Launch Mod ====
==== Rider Launch Mod ==== <!--T:175-->
<gallery mode="packed-hover" widths=500px heights=100px>
<gallery mode="packed-hover" widths="500px" heights="100px">
File:Rider-cp-start-new-ui.png|Rider Launch Mod (New UI)
File:Rider-cp-start-new-ui.png|Rider Launch Mod (New UI)
File:Rider-cp-start.png|Rider Launch Mod
File:Rider-cp-start.png|Rider Launch Mod
Line 252: Line 364:
If you are having trouble, you might be able to learn from the [https://github.com/anegostudios/vsmodexamples vsmodexamples project]
If you are having trouble, you might be able to learn from the [https://github.com/anegostudios/vsmodexamples vsmodexamples project]


== Packaging the Mod ==
== Packaging the Mod == <!--T:176-->


<!--T:177-->
With the new template, we are using the [https://cakebuild.net/ Cake] build system. This includes a second Project within the Solution in the template.  
With the new template, we are using the [https://cakebuild.net/ 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 <code>CakeBuild</code> option and run it.  
In all supported IDE's you can select from the dropdown that you used to launch the mod the <code>CakeBuild</code> option and run it.  
''When using Visual Studio Code you can also create a package by running the package task. For that got to <code>Terminal</code> > <code>Run Task...</code> and select <code>package</code>.''
''When using Visual Studio Code you can also create a package by running the package task. For that got to <code>Terminal</code> > <code>Run Task...</code> and select <code>package</code>.''


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


<!--T:179-->
Congratulations now you have your mod development environment set up and a ready-to-release mod package.
Congratulations now you have your mod development environment set up and a ready-to-release mod package.


<!--T:180-->
Note: Make sure you use your own unique <code>modid</code> else you won't be able to upload the mod to the VSModDB.
Note: Make sure you use your own unique <code>modid</code> else you won't be able to upload the mod to the VSModDB.
== Updating the Mod ==
If your mod is setup correctly, updating can be done by updating the <code>VINTAGE_STORY</code> envrionment variable to your new path.
Repeat the steps made in [[Modding:Setting up your Development Environment#Setup the Environment|Setup the Environment]] to edit the environment variable, and rebuild your mod. It is likely that mods will break on certain updates, however fixing them is often quite simplistic, and errors are well documented. To check your update has worked, debug your mod and check the game version on the main menu.


= Moving Forward = <!--T:70-->
= Moving Forward = <!--T:70-->
Line 274: Line 395:
<!--T:73-->
<!--T:73-->
Or head over to the '''[[Modding:Advanced Items | Advanced Items]]''' page to make your first advanced code item.
Or head over to the '''[[Modding:Advanced Items | Advanced Items]]''' page to make your first advanced code item.
<!--T:74-->
{{Navbox/modding|Vintage Story}}
</translate>
</translate>
{{Navbox/codemodding}}
Nateonus
Confirmedusers
711

edits

Retrieved from "https://wiki.vintagestory.at/index.php/Special:MobileDiff/111647...175610"