Modding:Simple Particles

VintageStory offers a variety of different types of particles. This tutorial will explain you how to create particles in code and show you some of the possibilities. If you want to have an example of where to use them I either suggested you to the read about the block particles or about collectibles. <- Add links

SimpleParticleProperties

Spawn particles

So let's spawn some really basic particles. I suggest to create a static field for your particle properties:

        public static SimpleParticleProperties myParticles = new SimpleParticleProperties(1, 1, ColorUtil.ColorFromArgb(50, 220, 220, 220), new Vec3d(), new Vec3d(), new Vec3f(), new Vec3f());

Now we have the property, the only thing what is left to do is to set the position and spawn them into the world. I'm gonna use the OnInteracting method inside the Item class (you can read more about this in the Collectibles Tutorial):

        public override bool OnInteracting(float secondsUsed, IItemSlot slot, IEntityAgent byEntity, BlockSelection blockSel, EntitySelection entitySel)
        {
            myParticles.minPos = byEntity.Pos.XYZ.Add(0, byEntity.EyeHeight(), 0).Ahead(1f, byEntity.Pos.Pitch, byEntity.Pos.Yaw);
            byEntity.World.SpawnParticles(myParticles);
        }

This will spawn some white cube particles, which simply fall to the ground. They are spawned right in front of the player.

Properties Overview

There are several things you can configure. Here is an overview which covers all of the basics properties:

Position

Basically there are two properties. One of them is the minPos property, which will determine the exact position where particles will spawn. addPos is relative to this position, once a particle will spawn it will be randomized and added to the particle's position. If addPos is not defined all particles will spawn at the exact some position.

Same position:

If we now set addPos ...

    myParticles.addPos = new Vec3d(0.5, 0.5, 0.5);

... particles will spawn in an 0.5³ area:

Velocity

It follows the same way as position. You can configure a minimum velocity (minPos) and an additional velocity (addPos).

    myParticles.minVelocity = new Vec3f(0, 3, 0);

In this case all particles have the same velocity (particles fly in the air but will eventually fall down again):

Life length

    myParticles.lifeLength = 0.2F;

    myParticles.lifeLength = 1F;

Quantity

    myParticles.minQuantity = 3;

    myParticles.minQuantity = 0;
    myParticles.addQuantity = 100;

Color

    myParticles.color = ColorUtil.ToRGBABytes(ColorUtil.ColorFromArgb(255, 255, 0, 0));

    Random rand = new Random();
    myParticles.color = ColorUtil.ToRGBABytes(ColorUtil.ColorFromArgb(255, rand.Next(0, 255), rand.Next(0, 255), rand.Next(0, 255)));

Glow

    myParticles.glowLevel = 20;

    myParticles.glowLevel = 255;

Gravity

    myParticles.gravityEffect = 0.1F;

Size

    myParticles.minSize = 0.1F;
    myParticles.maxSize = 1.0F;

    myParticles.minSize = 0.1F;
    myParticles.maxSize = 1.0F;
    myParticles.SizeEvolve = new EvolvingNatFloat(EnumTransformFunction.LINEAR, 2);

Model

    myParticles.model = EnumParticleModel.Quad;

Opacity

    myParticles.color = ColorUtil.ToRGBABytes(ColorUtil.ColorFromArgb(130, rand.Next(0, 255), rand.Next(0, 255), rand.Next(0, 255)));

    myParticles.OpacityEvolve = new EvolvingNatFloat(EnumTransformFunction.LINEAR, -255);