Modding:WorldGen API: Difference between revisions

We will be walking through how to plug in and add your own features to the world generation code of Vintage Story by looking at a demo mod called VSTreasureChest. The code for this project can be found [https://github.com/anegostudios/VSTreasureChest here]. We are going to walk through coding it from scratch. Please note that it is assumed that you are familiar with basic C# concepts. This document is strictly intended to familiarize you with the basic world gen api.

Please follow the instructions here[http://wiki.vintagestory.at/index.php?title=Setting_up_a_dev_environment] for setting up your development environment. We named our project VSTreasureChest but you can choose any name you like. We will do one different thing. When you get to the debug command line arguments instead of passing /flatworld we are going to pass /stdworld:test. The reason we are doing this is because we are going to be placing our chest beside a tree. The /flatworld generates a flat world with no trees so that won't help us much in this scenario. However, depending on the specific terrain gen features you are doing you may want to use /flatworld in the future.

     public class VSTreasureChestMod : ModBase

The first thing to note is the '''using''' directives at the top. Those that start with Vintagestory will allow us to access classes in the Vintagestory api. Next the '''StartServerSide''' is a method we are overriding from '''ModBase''' that is called once when the server is start up. Here we start by just storing a reference to the '''ICoreServerAPI''' for convenient access later. We will also be registering call backs for other events here.

The server does not generate chunks on the main game thread because the game's frame rate would drop significantly and it would really be disruptive to game play. The server spawns a separate thread for this and there is a special IBlockAccessor that is used in that thread that we need to get a reference to in order to place our chest. First lets add two variables at the top of our class of type IBlockAccessor. One to hold our game thread IBlockAccessor and one to hold the one used by the server world gen thread.

Let's initialize worldBlockAccessor at the top of StartServerSide. This is the IBlockAccessor we used in our /treasure command. Later we will refactor that code to use this variable.

Next we will register a call back delegate to be passed the IBlockAccessor we need. Place this in OnServerStart.

Let's do a quick refactoring before we move on. Remember our PlaceTreasureChestInFrontOfPlayer method? The code in that to place the chest is going to be reused by our world gen code but we won't have a player in that case and we will also need to use a different IBlockAccessor to place our block. So let's refactor that to use a new method we call PlaceTreasureChest. So replace PlaceTreasureChestInFrontOfPlayer with the following.

So what we did is make a PlaceTreasureChest that takes an IBlockAccessor and a BlockPos for placing the chest. The null check on chestEntity is probably not necessary however while developing this I found I was misusing the API by using the wrong IBlockAccessor so the null check helps detect this scenario and provides a more meaningful message than just a NullReferenceException so I suggest leaving this in. Also notice that we are printing a message to the console when a chest is placed. This is also optional however it's helpful for finding chests in the world when testing. Our PlaceTreasureChestInFrontOfPlayer method now calls our new method passing it the appropriate IBlockAccessor and the BlockPos 2 blocks in front of the player. Now that this refactoring has been done, we are ready to find a suitable spot to place our chests.

Now we are ready to place code in our OnChunkColumnGeneration to find a suitable spot for our chest. We are going to set up a nested for loop to loop through each x,y,z location in the chunk and see if that spot is beside a tree. Before we set up our loop we are going to add a few more variables at the top of our class.  

They are mostly self explanatory. The first one indicates how many chests we are going to allow to be placed per chunk. CHEST_SPAWN_PROBABILITY is a probability of placing a chest in the current chunk at all. chunkSize is just stored as a convenient way to access chunkSize. To initialize it we need the following in StartServerSide:

Make sure to add this after you set worldBlockAccessor!

I'll explain the treeTypes variable in a bit. Just add it for now.

Replace the empty OnChunkColumnGeneration with the following:

We've added a couple of methods here that I'll explain first. The ShouldPlaceChest method simply generates a random number between 0 and 100. If the number is between 0 and our CHEST_SPAWN_PROBABILITY multiplied by 100 then it returns true. This is called before we do our loop to see whether we should proceed in placing our chest. We will fill in the details of TryGetChestLocation in the next section so just leave it for now. The loop goes through each x, z then y coordinate and converts the coordinates to world coordinates by multiplying the chunkX coordinate by the chunkSize and adding our x coordinate in the loop. The same goes for Z. This is very important! Our IBlockAccessor expects world coordinates. World coordinates start at the beginning of the world whereas chunk coordinates start at the beginning of the chunk. Always keep your coordinate system in mind. Another thing to note here is that BlockPos is created outside our loop and reused to cut down on object creation. You don't want to create a ton of objects and cause garbage collection because this will negatively impact performance. Try to create as few objects as you can in code that will be executed frequently. The meat of the code calls our TryGetChestLocation to get a BlockPos. If the method returns null that means the current x,y,z is not a suitable location. However if it is then it moves on to our PlaceTreasureChest and increments the chestsPlaced counter which is used to check and make sure we aren't placing more chests in the chunk than MAX_CHESTS_PER_CHUNK.

 

Our loop and main logic is finished. Now it's time to implement TryGetChestLocation to detect trees.

Remember the treeTypes variable we created at the top of our class? Now it's time to populate that with the block codes of the tree logs we will be looking for. Let's add a method called LoadTreeTypes.

This method reads the log types from worldproperties/block/wood.json and adds them to our treeTypes set. Since we are looking for logs we prepend "log-" and we pick the variant "-ud" which means "Up/Down" since that's the variant of the tree log that is at the base of trees. Now to initialize our treeTypes set just add the following to StartServerSide:

Now to detect our logs we can simply compare the Block.Code property to values in our treeTypes set. Lets write a quick helper method for this:

The algorithm we will use to detect the tree log is pretty simple. We will see if the current block is a tree log, if so we will iterate downward to find the bottom log by detecting the first non-log type. Once we find it we simply find an adjacent air Block. Air blocks have a Block.Id value of 0. Here's the code:

<li>Currently the code will place chests over water or air. Change TryGetChestLocation to only place chests over solid blocks.</li>