90
edits
mNo edit summary |
mNo edit summary |
||
Line 1: | Line 1: | ||
{{GameVersion|1.13.2}} | |||
__FORCETOC__ | |||
This article requires a setup development environment. If you don't have one, read the tutorial | This article requires a setup development environment. If you don't have one, read the tutorial | ||
at | on [https://wiki.vintagestory.at/index.php?title=Modding:Setting_up_your_Development_Environment setting up your development environment.] For brevity, this article presupposes some familiarity with | ||
VintageStory code modding, primarily | VintageStory code modding, primarily [https://wiki.vintagestory.at/index.php?title=Modding:Mod_Packaging how mods are packaged] and [https://wiki.vintagestory.at/index.php?title=Modding:Setting_up_your_Development_Environment#Project_Setup_.28Compiled_Zip.29 how to setup a compiled mod project.] | ||
If you are looking to create your first mod, we recommend starting here | If you are looking to create your first code mod, we recommend starting [https://wiki.vintagestory.at/index.php?title=Modding:Advanced_Blocks here] instead. | ||
== Introduction == | == Introduction == | ||
VintageStory makes all loaded mods available through the API. | VintageStory makes all loaded mods available through it's expansive API, which you can explore in [http://apidocs.vintagestory.at/api/Vintagestory.API.Common.ICoreAPI.html the API docs.] | ||
This makes it possible for code mods to interact with eachother and access eachother's public properties. | This makes it possible for code mods to interact with eachother and access eachother's public properties. | ||
The loading and retrieving of mods is done through the | The loading and retrieving of mods is done through the [http://apidocs.vintagestory.at/api/Vintagestory.API.Common.IModLoader.html <code>IModLoader</code>], which we retrieve from [http://apidocs.vintagestory.at/api/Vintagestory.API.Common.ICoreAPI.html ICoreAPI]. We can retrieve both the full [http://apidocs.vintagestory.at/api/Vintagestory.API.Common.Mod.html <code>Mod</code>], with all it's useful data, as well as it's contained [http://apidocs.vintagestory.at/api/Vintagestory.API.Common.ModSystem.html <code>ModSystems</code>]. | ||
We can retrieve both the full | |||
This is superbly useful in multiple scenarios, for example - | This is superbly useful in multiple scenarios, for example - | ||
* Splitting up a large mod into smaller logical parts that communicate - a modpack. | * Splitting up a large mod into smaller logical parts that communicate - a modpack. | ||
* Extendable mods, for example - the creative tool for growing trees, which lets you register new tree types. | * Extendable mods, for example - the creative GUI tool for growing trees, which lets you register new tree types and easily test them. | ||
In this article, we will be creating two mods. Our first mod will provide a method for our second mod to interact with. | In this article, we will be creating two mods. Our first mod will provide a method for our second mod to interact with. | ||
We will demonstrate the use of the | We will demonstrate the use of the <code>ModLoader</code> and also explain how to reference an external mod and have that reference | ||
resolve at game runtime | resolve at game runtime. | ||
Note that, excluding the use of reflection or the use of an intermediary library, which is outside the scope of this article, | Note that, excluding the use of reflection or the use of an intermediary library, which is outside the scope of this article, | ||
<b>only compiled mods | <b>only compiled mods can interact with eachother</b>. | ||
== TipMod & SpawnMod == | == TipMod & SpawnMod == | ||
The two mods we will be creating are named "TipMod" and "SpawnMod". | The two mods we will be creating are named "TipMod" and "SpawnMod". | ||
* "TipMod" will store useful gameplay tips and periodically print them in chat. It will also provide a method which other mods can use to add their own tips. | |||
"TipMod" will store useful gameplay tips and periodically print them in chat. It will also provide a method which other mods | * "SpawnMod" will register a command which teleports the player to his set or default spawnpoint. It will also access "TipMod" and add it's own tips about the command. | ||
can use to add their own tips. | |||
"SpawnMod" will register a command which teleports the player to his set or default spawnpoint. It will also | |||
access "TipMod" and add it's own tips about the command. | |||
== Preperation == | == Preperation == | ||
We start by setting up two empty mods, "TipMod" and "SpawnMod". | We start by setting up two empty mods, "TipMod" and "SpawnMod". | ||
In each mod, we add a new *.cs source file - we will be naming these files TipMod.cs and SpawnMod.cs respectively. | In each mod, we add a new *.cs source file - we will be naming these files <code>TipMod.cs</code> and <code>SpawnMod.cs</code> respectively. | ||
In our .cs files, we do the following | In our .cs files, we do the following: | ||
* Add the necessary using directives. | * Add the necessary <code>using</code> directives. | ||
* Create a class named after the mod it's contained it. | * Create a class named after the mod it's contained it - <code>TipMod</code> and <code>SpawnMod</code>. | ||
* Have our classes inherit ModSystem - the base for any VintageStory code mod. | * Have our classes inherit <code>ModSystem</code> - the base for any VintageStory code mod. | ||
* Override the StartServerSide method to access the API. | * Override the <code>StartServerSide</code> method to access the <code>API</code>. | ||
* Make the TipMod class public so that it's accessible by other mods. | * Make the <code>TipMod</code> class <code>public</code> so that it's accessible by other mods. | ||
- img of folders - | - img of folders - | ||
Line 92: | Line 85: | ||
} | } | ||
</syntaxhighlight> | </syntaxhighlight> | ||
This concludes setting up the basis of our mods. Lastly, in TipMod, we create an additional file called Tip.cs, | This concludes setting up the basis of our mods. Lastly, in "TipMod", we create an additional file called <code>Tip.cs</code>, | ||
where we will define the data structure for tips. | where we will define the data structure for tips, called <code>Tip</code>. | ||
<syntaxhighlight lang="c#"> | <syntaxhighlight lang="c#"> | ||
Line 124: | Line 117: | ||
} | } | ||
</syntaxhighlight> | </syntaxhighlight> | ||
We are now ready to start adding the functionality of our mods. We will start with TipMod, as that will be our | We are now ready to start adding the functionality of our mods. We will start with "TipMod", as that will be our | ||
point of interaction. | point of interaction. | ||
== Setting up TipMod == | == Setting up TipMod == | ||
For "TipMod", we do the following. | |||
For TipMod, we do the following. | * Store the <code>ICoreServerAPI</code> object as a field so that we can access it throughout our class. | ||
* Store the | * Define a <code>List</code> that stores <code>Tip</code> objects. | ||
* Define a List that stores | * Create a method that selects a random <code>Tip</code> and prints it in chat for all players, printing a default message if there are no existing <code>Tip</code> objects. | ||
* Create a method that selects a random | * Register that method to be called at set intervals by the [http://apidocs.vintagestory.at/api/Vintagestory.API.Server.IServerEventAPI.html#Vintagestory_API_Server_IServerEventAPI_Timer_Vintagestory_API_Common_Action_System_Double_ <code>Timer</code>], which is available in the [http://apidocs.vintagestory.at/api/Vintagestory.API.Server.IServerEventAPI.html <code>ServerEventAPI</code>]. | ||
* Register that method to be called at set intervals by the | * Define a public method for adding new <code>Tip</code> objects. | ||
* Define a public method for adding new | |||
<syntaxhighlight lang="c#"> | <syntaxhighlight lang="c#"> | ||
Line 144: | Line 136: | ||
List<Tip> tips = new List<Tip>(); | List<Tip> tips = new List<Tip>(); | ||
double tipInterval = 10; | double tipInterval = 10; | ||
public override void StartServerSide(ICoreServerAPI api) | public override void StartServerSide(ICoreServerAPI api) | ||
{ | { | ||
Line 181: | Line 174: | ||
For testing purposes, we set the interval to be very short (10 seconds). Feel free to change this accordingly. | For testing purposes, we set the interval to be very short (10 seconds). Feel free to change this accordingly. | ||
Remember, both <b>classes and methods which other mods will interact with have to be declared public.</b> | Remember, both <b>classes and methods which other mods will interact with have to be declared <code>public</code>.</b> | ||
In C#, classes and methods are not public by default. You can read more about this here (https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/access-modifiers) | In C#, classes and methods are not public by default. You can read more about this here (https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/access-modifiers) | ||
We can now compile our mod, add it to our VintageStory mod folder and test it ingame. If the there are occasional chat messages | We can now compile our mod, add it to our VintageStory mod folder and test it ingame. If the there are occasional chat messages | ||
claiming that no tips are listed, our mod is working. We are ready to move on to the next step - setting up SpawnMod and then having it interact with TipMod. | claiming that no tips are listed, our mod is working. We are ready to move on to the next step - setting up "SpawnMod" and then having it interact with "TipMod". | ||
== Setting up SpawnMod == | == Setting up SpawnMod == | ||
Let's first setup our mods functionality | Let's first setup our mods functionality. We register a command which teleports the player to spawn. Conveniently, the [http://apidocs.vintagestory.at/api/Vintagestory.API.Server.IServerPlayer.html IServerPlayer] object stores it's spawn position, as well as the [http://apidocs.vintagestory.at/api/Vintagestory.API.Common.IPlayer.html#Vintagestory_API_Common_IPlayer_Entity IPlayerEntity], which defines a method for teleporting itself to a location. | ||
<syntaxhighlight lang="c#"> | <syntaxhighlight lang="c#"> | ||
class SpawnMod : ModSystem | class SpawnMod : ModSystem | ||
Line 204: | Line 197: | ||
} | } | ||
</syntaxhighlight> | </syntaxhighlight> | ||
SpawnMod is ready | "SpawnMod" is ready. Let's test it. The command <code>/spawn</code> should now teleport us to spawn. | ||
We've setup the base of our mods, now let's make SpawnMod interact with TipMod. | We've setup the base of our mods, now let's make "SpawnMod" interact with "TipMod". | ||
== Mods interacting == | == Mods interacting == | ||
Before we get started, we have to add a reference in SpawnMod to TipMod. If you are using Visual Studio, in your Solution Explorer, directly under your project, right-click "References" and select "Add Reference". | Before we get started, we have to add a reference in "SpawnMod" to "TipMod". If you are using Visual Studio, in your Solution Explorer, directly under your project, right-click "References" and select "Add Reference". | ||
- img - | - img - | ||
Here we locate either the TipMod project or the compiled .dll file and add it. | Here we locate either the "TipMod" project or the compiled .dll file, and add it. | ||
After adding the reference, make sure it is not copying the file to the output folder when compiling - | After adding the reference, make sure it is not copying the file to the output folder when compiling - | ||
having multiple .dll files with ModSystems in them will break your mod. | having multiple .dll files with <code>ModSystems</code> in them will break your mod. | ||
- img - | - img - | ||
Now we're ready to have SpawnMod add tips. Let's go ahead and do the following. | Now we're ready to have "SpawnMod" add tips. Let's go ahead and do the following. | ||
* Add a using directive for tipmod.src. | * Add a <code>using</code> directive for tipmod.src. | ||
* Retrieve TipMod through the ModLoader by passing it's type. | * Retrieve <code>TipMod</code> through the <code>ModLoader</code> by passing it's type. | ||
* Call the method provided by TipMod and add a variety of tips. | * Call the <code>AddTip</code> method provided by <code>TipMod</code> and add a variety of tips. | ||
<syntaxhighlight lang="c#"> | <syntaxhighlight lang="c#"> | ||
Line 363: | Line 356: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
We're now ready to test our mods to see if they're interacting successfully. After placing both our compiled mods in the mods folder, we should see a random tip pop up in the chat every 10 seconds. If so, well done! You've successfully followed the article and have created a moddable mod. | We're now ready to test our mods to see if they're interacting successfully. After placing both our compiled mods in the mods folder and loading into a world, we should see a random tip pop up in the chat every 10 seconds. If so, well done! You've successfully followed the article and have created a moddable mod. | ||
- img - | - img - | ||
== Troubleshooting == | == Troubleshooting == | ||
If you've ran into problems setting up either mod, check the error logs located at VintagestoryData/Logs in server-main.txt. | If you've ran into problems setting up either mod, check the error logs located at <code>VintagestoryData/Logs</code> in <code>server-main.txt</code>. | ||
Possible causes for either mod not working | Possible causes for either mod not working: | ||
* It's a .cs mod and not a .dll (compiled) mod. | * It's a .cs (source) mod and not a .dll (compiled) mod. Refer here [https://wiki.vintagestory.at/index.php?title=Modding:Setting_up_your_Development_Environment#Set_Mod for how to set a source mod into a compiled mod.] | ||
* It's missing modinfo.json. | * It's missing <code>modinfo.json</code>. | ||
* Your version of VintageStory is outdated. | * Your version of VintageStory is outdated. | ||
* You have multiple .dll files containing ModSystems in your mod folder. | * You have multiple .dll files containing <code>ModSystems</code> in your mod folder. | ||
* The referenced mod is not present in the mod folder. | * The referenced mod, "TipMod", is not present in the mod folder. | ||
== Distribution == | == Distribution == | ||
To distribute this mod, run the following command in the vsmodtools cli <code>pack <your mod id></code>, then copy the .zip file into your VintageStory mods folder. | |||
Here are the official versions: | |||
* for VS v1.13.2: [https://wiki.vintagestory.at/index.php?title=File:TipMod_vs1.13.2_v1.0.0.zip File:TipMod_vs1.13.2_v1.0.0.zip] and [https://wiki.vintagestory.at/index.php?title=File:SpawnMod_vs1.13.2_v1.0.0.zip File:SpawnMod_vs1.13.2_v1.0.0.zip]. | |||
{{Navbox/modding|Vintage Story}} | |||
edits