Modding:World Access

This page was last verified for Vintage Story version 1.19.3.

Get and Set Blocks through the API

Let's Take our basic mod init code for a server mod

    public class SampleMod : ModSystem
    {
        ICoreServerAPI api;

        public override bool ShouldLoad(EnumAppSide side)
        {
            return side == EnumAppSide.Server;
        }


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

With this you can already start placing or reading blocks using the api object. Please note that mods are loaded before the world is loaded, so you cannot immediately access the world. Depending on what you want to achieve, you have to register to the appropriate event. For some examples in order to do something...

• after the world has loaded you could register to the RunGame phase: api.Event.ServerRunPhase(EnumServerRunPhase.RunGame, OnRunGame);
• during world generation we'd have to register to the appropriate world gen events.
• when the player runs a custom command we need to register one: api.RegisterCommand("test", "a test command", "", OnCommand);
• when a player joins the game: api.Event.PlayerJoin += OnPlayerJoin;

Let's register to the player join event.

        public override void StartServerSide(ICoreServerAPI api)
        {
            this.api = api;
            api.Event.PlayerJoin += OnPlayerJoin;
        }

        private void OnPlayerJoin(IServerPlayer byPlayer)
        {
            
        }

Let's do 2 simple things whenever a player joins:

• Always place some fire clay bricks just below his feet
• Count the amount log blocks around the player in a 3 block radius

Now, blocks are always uniquely identified by a number of characters called the block code. If you want to find out a blocks code, a simple way of doing it is to start the game, enable the debug info mode via the command .edi and look at a block in the creative inventory:

So the code of a fire brick block is game:claybricks-fire. The first part before the colon is the domain, for the default domain 'game' we can usually ignore it.

We now have to retrieve it's number identifier for this particular world in order to get or set it. We do this as followed:

        private void OnPlayerJoin(IServerPlayer byPlayer)
        {
            Block firebrickblock = api.World.GetBlock(new AssetLocation("claybricks-fire"));
            int blockId = firebrickblock.BlockId;
        }

Now all we have to do is set the block right below the players position through the IBlockAccessor interface.

            BlockPos plrpos = byPlayer.Entity.Pos.AsBlockPos;
            api.World.BlockAccessor.SetBlock(blockId, plrpos.DownCopy());

We're using plrpos.DownCopy() to keep the original player position for later use and to move the position down by 1 for placing the block below the player.

And finally let's count the number of log blocks around the player and inform him via chat message.

            // Check a 7x7x7 area for logs
            int quantityLogs = 0;
            for (int x = -3; x <= 3; x++)
            {
                for (int y = -3; y <= 3; y++)
                {
                    for (int z = -3; z <= 3; z++)
                    {
                        Block block = api.World.BlockAccessor.GetBlock(new BlockPos(plrpos.X + x, plrpos.Y + y, plrpos.Z + z, plrpos.dimension));
                        
                        if (block.Code.Path.Contains("log"))
                        {
                            quantityLogs++;
                        }                        
                    }
                }
            }

            byPlayer.SendMessage(GlobalConstants.GeneralChatGroup, "You have " + quantityLogs + " logs nearby you", EnumChatType.Notification);

Alternatively we could also use a shorthand method to have more elegant code.

            int quantityLogs = 0;
            api.World.BlockAccessor.WalkBlocks(
                plrpos.AddCopy(-3, -3, -3), 
                plrpos.AddCopy(3, 3, 3), 
                (block, x, y, z) => quantityLogs += block.Code.Path.Contains("log") ? 1 : 0
            );

            byPlayer.SendMessage(GlobalConstants.GeneralChatGroup, "You have " + quantityLogs + " logs nearby you", EnumChatType.Notification);

And the complete code and final result:

        private void OnPlayerJoin(IServerPlayer byPlayer)
        {
            Block firebrickblock = api.World.GetBlock(new AssetLocation("claybricks-fire"));
            int blockId = firebrickblock.BlockId;

            BlockPos plrpos = byPlayer.Entity.Pos.AsBlockPos;
            api.World.BlockAccessor.SetBlock(blockId, plrpos.DownCopy());

            // Check a 7x7x7 area for logs
            int quantityLogs = 0;
            api.World.BlockAccessor.WalkBlocks(
                plrpos.AddCopy(-3, -3, -3),
                plrpos.AddCopy(3, 3, 3),
                (block, x, y, z) => quantityLogs += block.Code.Path.Contains("log") ? 1 : 0
            );

            byPlayer.SendMessage(GlobalConstants.GeneralChatGroup, "You have " + quantityLogs + " logs nearby you", EnumChatType.Notification);

        }

I hope this taught you the basics of accessing the world. More ways to access blocks and entities will be added here in the future.

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.