Modding:Advanced Blocks

It's highly recommended to read Creating Blocks first. Additionally this tutorial requires a development environment. If you don't have one already you should read the tutorial Setting up a dev environment.

Trampoline

In this tutorial will we create something more advanced. A block with functionality ... a trampoline!

Block Assets

The first thing we are going to need are the assets of the block. Those are pretty straight forward.

The only new property is the class:

	class: "trampoline",

We will create this class, to give the block the desired functionality, so make sure if you pick a different name it matches the one below. You can download the assets of the mod here. All you need to do is to place this zip file in your mods directory of your development environment.

The Block Class

Now we need to register our class and therefore we need to create a new *.cs file in our project. I'm gonna name it Trampoline.cs.

The Mod Base

In order to create a mod your class needs to extend ModBase. This will allow use to register all kinds of stuff, but for now we will stick to our block class example.

public class TrampolineMod : ModBase
{
    
}

Now you need to override the Start(ICoreAPI) method and register the class. If you have picked a different class name you have to use that one instead of trampoline.

public class TrampolineMod : ModBase
{
    public override void Start(ICoreAPI api)
    {
        base.Start(api);
        api.RegisterBlockClass("trampoline", typeof(TrampolineBlock));
    }
}

This should be marked as a syntax error because there is no TrampolineBlock class yet.

The Block Class

Let's create our block class itself which of course has to extend Block:

public class TrampolineBlock : Block
{

}

This should solve all syntax errors.

So how do we implement a bouncy block? It's pretty helpful to take a look at the api documentation to find a proper way to implement it.

The method void onEntityCollide(IWorldAccessor world, Entity entity, BlockPos pos, BlockFacing facing, bool isImpact) seems to be a good way to implement a bouncy functionality.

When should an entity bounce?

1. The entity should bounce in the moment it lands on top of the block and not if it is standing on it already. Therefore isImpact has to be true
2. If the entity is colliding vertically. The sides of the block shouldn't push an entity away. So the axis of the facing has to be Y.

How can we make the entity bounce? In order to make an entity bounce, we need to change its direction. Therefore we can simply revert its motion. The faster the entity will be when during the collision the further it will be pushed away. But simply reverting the motion wouldn't be ideal. The entity would never lose its motion and bounce endless. So let's go for something smaller and make the entity lose 20% of its motion each bounce:

entity.Pos.Motion.Y *= -0.8;

---

If we put everything together it should look like this:

public class TrampolineBlock : Block
{
    public override void onEntityCollide(IWorldAccessor world, Entity entity, BlockPos pos, BlockFacing facing, bool isImpact)
    {
        if (isImpact && facing.Axis == EnumAxis.Y)
        {
            entity.Pos.Motion.Y *= -0.8;
        }
    }
}

Although this code works already, some sound effects would be rather nice. This will played every time an entity bounces:

entity.PlayEntitySound("tick", EnumAppSide.Server);

---

If you have done everything right, your file should look similar to this:

using Vintagestory.API.Common;
using Vintagestory.API.Common.Entities;
using Vintagestory.API.MathTools;

namespace VSExampleMods
{
    public class TrampolineMod : ModBase
    {
        public override void Start(ICoreAPI api)
        {
            base.Start(api);
            api.RegisterBlockClass("trampoline", typeof(TrampolineBlock));
        }
    }

    public class TrampolineBlock : Block
    {
        public override void onEntityCollide(IWorldAccessor world, Entity entity, BlockPos pos, BlockFacing facing, bool isImpact)
        {
            if (isImpact && facing.Axis == EnumAxis.Y)
            {
                entity.PlayEntitySound("tick", EnumAppSide.Server);
                entity.Pos.Motion.Y *= -0.8;
            }
        }
    }
}

Of course you can download the file directly Trampoline.cs.

Testing

Finally we can run our first test. Looks pretty good, right?

Distributing a mod

In order to finish everything, you need to place your *.cs file in the zip archive. Once that is done you can 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.

Here is my version: Trampoline.zip