WorldGen

From Vintage Story Wiki
Jump to navigation Jump to search

Intro

We will be walking through how 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 here [1] but 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.

VSTreasureChest

This mod places treasure chests around the world for the user to find. Each treasure chest has a random number of ingots in them. The mod only places treasure chests beside trees. It also adds a server command that can be run in the chat window called /treasure that places a treasure chest in front of the player. This can be useful for testing in case you want to change what items are in the chest and you don't want to bother looking for the chest for verification.


Getting started

Please follow the instructions here[2] 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.


The mod class

The main class and the starting point of our mod will be VSTreasureChestMod.

using System;
using System.Collections.Generic;
using Vintagestory.API;
using Vintagestory.API.Datastructures;
using Vintagestory.API.Interfaces;

namespace Vintagestory.Mods.TreasureChest
{
    public class VSTreasureChestMod : ModSystem
    {
        private ICoreServerAPI api;

        public override void StartServerSide(ICoreServerAPI api)
        {
            this.api = api;
        }
    }
}

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 ModSystem 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 /treasure command

Next we are going to add the /treasure command. To do this we must register a delegate so that we can be notified when the user types our command. We do this with the ICoreServerAPI.RegisterCommand method.

In StartServerSide add the following line:

this.api.RegisterCommand("treasure", "Place a treasure chest with random items", "", PlaceTreasureChestInFrontOfPlayer, Privilege.controlserver);

This is registering a treasure command with the server with a brief description that is used to describe the command for when the user types /help. The other important argument is the PlaceTreasureChestInFrontOfPlayer argument which is a reference to a method we haven't written yet. So lets add the following method below StartServerSide.

private void PlaceTreasureChestInFrontOfPlayer(IServerPlayer player, int groupId, CmdArgs args)
{
}

This method will now be called when the user types /treasure command in the chat window. Wasn't that easy!!! Now we need to write the code to place our chest in that method.


Placing our chest

The first thing we need to do is figure out how to tell the API that we want a chest and not grass or stone or some other block. Every Block has a numerical ID that gets assigned when the server starts but this ID may change. Luckily there is a property of the Block class that identifies it and does not change. This is the Code property. Block codes can be found in Vintagestory\assets\blocktypes in json files. The one for chest is Vintagestory\assets\blocktypes\wood\generic\chest.json. If you open that file you will see at the very top the code property is set to "chest". We also need to append the type of the shape that basically tells the system which way the chest is facing. So for simplicity we are going to pick south. So the resulting block code we will be using is "chest-south". Ok lets see some code.

private void PlaceTreasureChestInFrontOfPlayer(IServerPlayer player, int groupId, CmdArgs args)
{
    ushort blockID = api.WorldManager.GetBlockId("chest-south");
    Block chest = api.WorldManager.GetBlockType(blockID);
    chest.TryPlaceBlockForWorldGen(api.World.BlockAccessor, player.Entity.Pos.HorizontalAheadCopy(2).AsBlockPos, BlockFacing.UP);
}

The first line of code asks the IWorldManagerAPI to get the numeric block id for the block code "chest-south". Next we get the Block class that represents that chest. And finally we call a method called TryPlaceBlockForWorldGen and pass in an IBlockAccessor. There are many implementations of IBlockAccessor and we will cover that in a little more detail later. For now we are using this one. The second argument just calculates the world coordinates for 2 blocks in front of the player.

Now if you run the mod from Visual Studio by pressing "Start" at the top you should be able to execute the /treasure command in the game. Once you do that you will have a fancy new chest appear in front of you with no items. Well I guess it's time for us to add some items.


Adding items to our chest

We want to add some items to the chest since after all it is a "treasure" chest. For now we are going to add various ingots to the chest. However there are lots of items in Vintagestory and I encourage you to play with this and feel free to add other items. We also want to add items at random. Not only the type of items should be random but also the ingots we add should be random. There are all kinds of ways to do this but lets write a data structure that represents a grab bag full of items and lets pull items out of that bag and place them in the chest like Santa Claus! We will create a ShuffleBag class so in Visual Studio right click on your project and go to Add->Class. Call it ShuffleBag.cs and press Add. Here's the code to place in the ShuffleBag class.

using System;
using System.Collections.Generic;

namespace Vintagestory.Mods.TreasureChest
{
    /// <summary>
    /// Data structure for picking random items
    /// </summary>
    public class ShuffleBag<T>
    {
        private Random random = new Random();
        private List<T> data;

        private T currentItem;
        private int currentPosition = -1;

        private int Capacity { get { return data.Capacity; } }
        public int Size { get { return data.Count; } }

        public ShuffleBag(int initCapacity)
        {
            this.data = new List<T>(initCapacity);
            this.random = new Random();
        }

        public ShuffleBag(int initCapacity, Random random)
        {
            this.random = random;
            this.data = new List<T>(initCapacity);
        }

        /// <summary>
        /// Adds the specified number of the given item to the bag
        /// </summary>
        public void Add(T item, int amount)
        {
            for (int i = 0; i < amount; i++)
                data.Add(item);

            currentPosition = Size - 1;
        }

        /// <summary>
        /// Returns the next random item from the bag
        /// </summary>
        public T Next()
        {
            if (currentPosition < 1)
            {
                currentPosition = Size - 1;
                currentItem = data[0];

                return currentItem;
            }

            var pos = random.Next(currentPosition);

            currentItem = data[pos];
            data[pos] = data[currentPosition];
            data[currentPosition] = currentItem;
            currentPosition--;

            return currentItem;
        }
    }
}

This is all basic C# stuff but the idea is that we are going to call Add on our ShuffleBag several times to load it up, then we are going to call Next to pull items out of it. This will let us kind of control the probability or rarity of items placed in chests. Items that are more rare will have fewer items in the bag.

Lets add a couple of class variables to control the minimum and maximum number of items that will go in our chest.

private const int MIN_ITEMS = 3;
private const int MAX_ITEMS = 10;

Since we will want to create a new ShuffleBag with each chest we place lets go ahead and create a MakeShuffleBag method.

private ShuffleBag<string> MakeShuffleBag()
{
    ShuffleBag<string> shuffleBag = new ShuffleBag<string>(100, api.World.Rand);
    shuffleBag.Add("ingot-iron", 10);
    shuffleBag.Add("ingot-bismuth", 5);
    shuffleBag.Add("ingot-silver", 5);
    shuffleBag.Add("ingot-zinc", 5);
    shuffleBag.Add("ingot-titanium", 5);
    shuffleBag.Add("ingot-platinum", 5);
    shuffleBag.Add("ingot-chromium", 5);
    shuffleBag.Add("ingot-tin", 5);
    shuffleBag.Add("ingot-lead", 5);
    shuffleBag.Add("ingot-gold", 5);
    return shuffleBag;
}

This loads up our ShuffleBag with various ingots. The only more common item is iron. Feel free to change the item counts as you see fit. One thing to note here is the API does give us an instance of Random that we can use so we pass it in to our ShuffleBag.

We are almost ready to place these items in the chest but we need to create an ItemStack for each slot we will be taking up in the chest. The chest is an instance of IBlockEntityContainer which has an Inventory property. An Inventory is made up of several IItemSlot instances. We need a utility method to create a list of ItemStacks to place in those slots.

private IEnumerable<ItemStack> MakeItemStacks()
{
    ShuffleBag<string> shuffleBag = MakeShuffleBag();
    Dictionary<string, ItemStack> itemStacks = new Dictionary<string, ItemStack>();
    int grabCount = api.World.Rand.Next(MIN_ITEMS, MAX_ITEMS);
    for (int i = 0; i < grabCount; i++)
    {
        string nextItem = shuffleBag.Next();
        Item item = api.World.GetItem(nextItem);
        if (itemStacks.ContainsKey(nextItem))
        {
            itemStacks[nextItem].StackSize++;
        }
        else
        {
            itemStacks.Add(nextItem, new ItemStack(item));
        }
    }
    return itemStacks.Values;
}

Here we make our ShuffleBag by calling MakeShuffleBag. We calculate a grabCount which is random number between MIN_ITEMS and MAX_ITEMS that controls the number of times Santa is going to reach into his bag. We don't want to create an ItemStack for each item because we may get 3 iron ingots for example. We don't want 3 slots with one iron ingot, we want one slot with 3 iron ingots. So we create a Dictionary and add items of the same type to the same ItemStack. This method returns an IEnumerable that we can loop over so we need to add a method that can loop over a list of ItemStacks and add them to our chest.

private void AddItemStacks(IBlockEntityContainer chest, IEnumerable<ItemStack> itemStacks)
{
    int slotNumber = 0;
    foreach (ItemStack itemStack in itemStacks)
    {
        slotNumber = Math.Min(slotNumber, chest.Inventory.QuantitySlots - 1);
        IItemSlot slot = chest.Inventory.GetSlot(slotNumber);
        slot.Itemstack = itemStack;
        slotNumber++;
    }
}

This method does just that. It advances the IItemSlot number each time, ensuring not to place more ItemStacks than there are IItemSlots, and sets the IItemSlot.ItemStack value to the current ItemStack in the loop. We are almost there! We have all the pieces. Now we just need to get a reference to our chest that we have already placed and pass it to this method along with the ItemStacks.

Lets go back to our PlaceTreasureChest method and replace the last line with the following code snippet.

BlockPos pos = player.Entity.Pos.HorizontalAheadCopy(2).AsBlockPos;
chest.TryPlaceBlockForWorldGen(api.World.BlockAccessor, pos, BlockFacing.UP);
IBlockEntityContainer chestEntity = (IBlockEntityContainer)api.World.BlockAccessor.GetBlockEntity(pos);
AddItemStacks(chestEntity, MakeItemStacks());

The first line is just capturing the BlockPos position object so that we can use it in two places. The next is the same as before, just placing the chest in the world. Next we go back to the IBlockAccessor to get the block entity at that position. It's important to call GetBlockEntity here because a chest is an Entity. An Entity is something that has extra behavior attached to it as opposed to a normal block. This method returns an IBlockEntity which is a generic interface for all block entities. However we specifically need a block entity that has an Inventory. Since we know the block entity we just placed is a chest then it's safe to to cast the returned IBlockEntity to an IBlockEntityContainer which is a specialized version of IBlockEntity that provides access to an Inventory. Now that we have that we pass it along to our AddItemStacks method we created earlier and additionally pass in the list of ItemStacks that are created by our MakeItemStacks method that we also created earlier. Now if you run the code again and type /treasure you should have random items in there! Try it several times and you will see them change.

That's really cool and all but not real fun for a game play experience. We want the player to find these chests and encourage them to explore the world! So lets plug in to world gen next!

Hooking in to the world gen API

The IServerEventAPI has a method called ChunkColumnGeneration that allows you to pass a delegate just like we did for our /treasure command. However, the method signature for this is different. TODO:


Finding where to place the chest

TODO


Excercises

A few things could be done to improve this code and it's left as an exercise for the reader. Doing this will help you get familiar with the API without overwhelming you.

  • Make chests a more rare item to find.
  • Currently the code will place chests over water or air. Change TryGetChestLocation to only place chests over solid blocks.
  • Chests should have more interesting items. Modify the code to put some more useful things in there. Maybe tools or weapons that can't be crafted.
  • A harder exercise might be to only place chests in caves.


Vintage Story: Modding
Basics Mod Types | Asset System | Textures | Items | Recipes | Blocks | Model Creator | Release
Advanced Setup(Windows,Linux) | Items (Code, JSON) | Blocks | Item-Block interactions | Block Behaviors | Block Entities | Particles | World Access
Worldgen Terrain | Ores | Trees | WorldGen API
Rendering Shaders and Renderers
Property Overview Item | Block | Block Behaviors | Block Classes | Block Entities | Block Entity Behaviors