World Access

From Vintage Story Wiki
Jump to: navigation, search

Get and Set Blocks through the API

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

    public class SampleMod : ModBase
    {
        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:

Blockcode.png

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"));
            ushort 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 3x3x3 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(plrpos.X + x, plrpos.Y + y, plrpos.Z + z);

                        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, pos) => 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)
        {
            BlockPos plrpos = byPlayer.Entity.Pos.AsBlockPos;

            Block firebrickblock = api.World.GetBlock(new AssetLocation("claybricks-fire"));
            ushort blockId = firebrickblock.BlockId;
            api.World.BlockAccessor.SetBlock(blockId, plrpos.DownCopy());

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

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

SetblockTut.png


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.



Vintage Story: Modding

Basics

Mod TypesAsset SystemTexturesItemsRecipesBlocksModel CreatorRelease

Advanced

Setup(Windows,Linux) ♦ Items ♦ BlocksItem-Block interractionsBlock BehaviorBlock EntityParticlesWorld Access

Worldgen

Terrain ♦ Ores ♦ Trees ♦ Worldgen API

Rendering

Shaders and Renderers

Property Overview

ItemBlock