Modding:Block Entity

From Vintage Story Wiki
Jump to navigation Jump to search

This page was last verified for Vintage Story version 1.16.


Introduction

A block entity is a construct that you can tack onto an existing block to give it additional functionality. Whenever a block should do something on a regular interval or store extra information, such as the contents of a chest block, you need a block entity. It's highly recommend to have read the tutorial about Basic Blocks and Block Class in order to understand this tutorial properly.

The Texture Flipper

Let's create a block which switches its texture every 3 seconds. It should have two variants "on" and "off". Additionally we need to define the blockentity class like so:

	entityClass: "tickingcounter",

You can download the assets here and place it in your mods directory.

The BlockEntity

Now we need to register our blockentity class and therefore we need to create a new *.cs file in our project. Let's name it Ticking.cs.

First of all you need to create the blockentity class itself. Therefore you need to extend BlockEntity:

    public class TickingBlockEntity : BlockEntity
    {
    
    }

This class needs to have a timer, once the timer reaches 3 seconds it should replace the current block with the different state.

In order to create a timer we need to register a tick listener. Therefore we need to override Initialize(ICoreAPI):

        public override void Initialize(ICoreAPI api)
        {
            base.Initialize(api);
        }

add a counter (which should increase per tick) ...

        public float timer;

... and the actual ticking method ...

        public void OnGameTick(float dt)
        {
        
        }

To register the ticking method we can use RegisterGameTickListener in Initialize

        public override void Initialize(ICoreAPI api)
        {
            base.Initialize(api);
            RegisterGameTickListener(OnGameTick, 50);
        }

The timer itself should increment by dt, the time difference in seconds between the current tick and the previous tick. It ticks about every 50ms or less often if the game is slow. So if the timer is greater than 3, it should replace the block:

        public void OnGameTick(float dt)
        {
            timer += dt;
            if(timer >= 3)
            {
                Block block = Api.World.BlockAccessor.GetBlock(Pos);
                if (block.Code.Path.EndsWith("-on"))
                {
                    block = Api.World.GetBlock(block.CodeWithParts("off"));
                }
                else
                {
                    block = Api.World.GetBlock(block.CodeWithParts("on"));
                }

                Api.World.BlockAccessor.SetBlock(block.BlockId, Pos);
            }
        }

Furthermore we need to save the current time:

        public override void ToTreeAttributes(ITreeAttribute tree)
        {
            base.ToTreeAttributes(tree);
            tree.SetFloat("timer", timer);
        }

        public override void FromTreeAttributes(ITreeAttribute tree, IWorldAccessor worldForResolving)
        {
            base.FromTreeAttributes(tree, worldForResolving);
            timer = tree.GetFloat("timer");
        }

Registering the Block Entity

Registering the blockentity class is rather simple (rather similar to registering a block class). You need a mod class and override Start(ICoreAPI):

    public class Ticking : ModSystem
    {

        public override void Start(ICoreAPI api)
        {
            base.Start(api);
            api.RegisterBlockEntityClass("tickingcounter", typeof(TickingBlockEntity));
        }

    }

Testing

Now everything is ready to run the first test:

Distribution

In order to finish everything, open the modtools and type in pack <your mod id>. Now you can take the zip file and share it with other people. It will work in the same way as ordinary mods, you can install it by copying it into the mods folder.

Mod Download



Modding
Template:Navbox/modding/code require C# coding
Basics

Getting Started | Mod Types | Simple Examples | Theme Pack

Asset System | Textures | Items | Recipes | Blocks | Entities | Model Creator | Animation Basics | VTML & Icons | Mod Packaging & Release | Modinfo | Debugging

Advanced

JSON Patching | Advanced JSON Items | The Remapper | Server-Client Considerations | Compatibility with other mods

Setting Up Your Development Environment (General - Windows - Linux)

Advanced Blocks | Advanced Items | Item-Block Interactions | Block Behavior | Block Entities | Particle Effects | World Access | Inventory Handling | Chat Commands | GUIs | Server-Client Networking | Monkey patching (Harmony)

Data Management

Savegame Data Storage | ModConfig File | Chunk Data Storage | Tree Attribute

Worldgen

WorldGen Concepts | Terrain | Ores | Trees | WorldGen API

Rendering

Shaders and Renderers

Property Overview

Item | Entity | Block | Block Behaviors | Block Classes | Block Entities | Block Entity Behaviors

Workflows & Infrastructure

Modding Efficiency Tips | Mod-engine compatibility | Mod Extensibility | Load Order

Additional Resources

List of server commands | List of client commands | Client startup parameters | Creative Starter Guide | ServerBlockTicking | Bot System | WorldEdit | Cinematic Camera

Example Mods | API Docs | GitHub Repository