Modding:Simple Particles: Difference between revisions

From Vintage Story Wiki
m (CreativeMD moved page Particles to Simple Particles)
m (VeryGoodDog moved page Simple Particles to Modding:Simple Particles)
(3 intermediate revisions by 3 users not shown)
Line 1: Line 1:
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
VintageStory offers a variety of different types of particles. This tutorial will explain you how to create simple particles 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 Json Properties#p_particleproperties|block particles]] or about [[Collectible|collectibles]].


== Spawn particles ==
== Spawn particles ==


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


<syntaxhighlight lang="c#">
<syntaxhighlight lang="c#">
Line 9: Line 9:
</syntaxhighlight>
</syntaxhighlight>


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 <code>OnInteracting</code> method inside the Item class (you can read more about this in the Collectibles Tutorial):
Now we have the property, the only thing left to do is to set the position and spawn the particles into the world. I'm gonna use the <code>OnHeldInteractStart</code> and *Step method inside a custom made Item class (you can read more about this in the [[Collectible|Collectibles Tutorial]]):
<syntaxhighlight lang="c#">
<syntaxhighlight lang="c#">
         public override bool OnInteracting(float secondsUsed, IItemSlot slot, IEntityAgent byEntity, BlockSelection blockSel, EntitySelection entitySel)
        public override void OnHeldInteractStart(ItemSlot slot, EntityAgent byEntity, BlockSelection blockSel, EntitySelection entitySel, ref EnumHandHandling handHandling)
        {
            handHandling = EnumHandHandling.Handled;
        }
 
         public override bool OnHeldInteractStep(float secondsUsed, ItemSlot slot, EntityAgent byEntity, BlockSelection blockSel, EntitySelection entitySel)
         {
         {
             myParticles.minPos = byEntity.Pos.XYZ.Add(0, byEntity.EyeHeight(), 0).Ahead(1f, byEntity.Pos.Pitch, byEntity.Pos.Yaw);
             myParticles.minPos = byEntity.Pos.XYZ.Add(0, byEntity.EyeHeight(), 0).Ahead(1f, byEntity.Pos.Pitch, byEntity.Pos.Yaw);
             byEntity.World.SpawnParticles(myParticles);
             byEntity.World.SpawnParticles(myParticles);
            return true;
         }
         }
</syntaxhighlight>
</syntaxhighlight>


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


[[File:BasicParticles.png|300px]]
[[File:BasicParticles.png|300px]]
Line 24: Line 31:
== Properties Overview ==
== Properties Overview ==


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


=== Position ===
=== Position ===
Line 57: Line 64:


=== Life length ===
=== Life length ===
This property is pretty straight forward. A life length of one equals one second.
Particles will exist for one 200 milliseconds ...


<syntaxhighlight lang="c#">
<syntaxhighlight lang="c#">
Line 63: Line 74:


[[File:Particles (short life).gif|300px]]
[[File:Particles (short life).gif|300px]]
Particles will exist for one second ...


<syntaxhighlight lang="c#">
<syntaxhighlight lang="c#">
Line 71: Line 85:


=== Quantity ===
=== Quantity ===
Determines how many particles will spawn.


<syntaxhighlight lang="c#">
<syntaxhighlight lang="c#">
     myParticles.minQuantity = 3;
     myParticles.minQuantity = 3;
</syntaxhighlight>
</syntaxhighlight>
This will spawn 3 particles each tick.


[[File:Particles (many).gif|300px]]
[[File:Particles (many).gif|300px]]
Furthermore you can specify an additional quantity chance ...


<syntaxhighlight lang="c#">
<syntaxhighlight lang="c#">
Line 82: Line 102:
     myParticles.addQuantity = 100;
     myParticles.addQuantity = 100;
</syntaxhighlight>
</syntaxhighlight>
This will spawn 0 to 100 particles per tick.


[[File:Particles (random many).png|300px]]
[[File:Particles (random many).png|300px]]


=== Color ===
=== Color ===
A color can be specified using ARGB (Alhpa, Red, Green, Blue). All values have a range of 0 to 255.


<syntaxhighlight lang="c#">
<syntaxhighlight lang="c#">
     myParticles.color = ColorUtil.ToRGBABytes(ColorUtil.ColorFromArgb(255, 255, 0, 0));
     myParticles.color = ColorUtil.ToRGBABytes(ColorUtil.ColorFromArgb(255, 255, 0, 0));
</syntaxhighlight>
</syntaxhighlight>
This will spawn red particles ...


[[File:Particles (red).gif|300px]]
[[File:Particles (red).gif|300px]]
Line 97: Line 123:
     myParticles.color = ColorUtil.ToRGBABytes(ColorUtil.ColorFromArgb(255, rand.Next(0, 255), rand.Next(0, 255), rand.Next(0, 255)));
     myParticles.color = ColorUtil.ToRGBABytes(ColorUtil.ColorFromArgb(255, rand.Next(0, 255), rand.Next(0, 255), rand.Next(0, 255)));
</syntaxhighlight>
</syntaxhighlight>
This will spawn particles with a random color ...


[[File:Particles (random colors).gif|300px]]
[[File:Particles (random colors).gif|300px]]


=== Glow ===
=== Glow ===
This property allows you to define whether the particles will be visible in the dark or not ...


<syntaxhighlight lang="c#">
<syntaxhighlight lang="c#">
Line 115: Line 145:


=== Gravity ===
=== Gravity ===
Gravity effect can not only be increase or decreased, ...


<syntaxhighlight lang="c#">
<syntaxhighlight lang="c#">
Line 121: Line 153:


[[File:Particles (low gravity).gif|300px]]
[[File:Particles (low gravity).gif|300px]]
...  but you can also disable it completely (using zero gravity) or invert it (particles will fly up).


=== Size ===
=== Size ===
Again, you can specify a minimum size and an additional randomized size ...


<syntaxhighlight lang="c#">
<syntaxhighlight lang="c#">
Line 130: Line 166:


[[File:Particles (random size).gif|300px]]
[[File:Particles (random size).gif|300px]]
Furthermore you can specify a <code>SizeEvolve</code> like so ...


<syntaxhighlight lang="c#">
<syntaxhighlight lang="c#">
Line 138: Line 176:


[[File:Particles (growing size).gif|300px]]
[[File:Particles (growing size).gif|300px]]
There are many EnumTransformFunctions you can play around with. Linear is the most basic one.


=== Model ===
=== Model ===
There are two types of models. <code>Cube</code> (the one we used so far) and <code>Quads</code>:


<syntaxhighlight lang="c#">
<syntaxhighlight lang="c#">
Line 148: Line 190:


=== Opacity ===
=== Opacity ===
Quads support custom opacity. This allows you to make them transparent ...


<syntaxhighlight lang="c#">
<syntaxhighlight lang="c#">
Line 154: Line 198:


[[File:Particles (opacity).gif|300px]]
[[File:Particles (opacity).gif|300px]]
Similar to <code>SizeEvolve</code> you can add an <code>OpacityEvolve</code> ...


<syntaxhighlight lang="c#">
<syntaxhighlight lang="c#">
Line 162: Line 208:


=== Self Propelled ===
=== Self Propelled ===
This property will make particles don't lose their velocity, even if they would collide with something, as soon as there is enough space they will continue to fly in the direction (with the same speed) ...


<syntaxhighlight lang="c#">
<syntaxhighlight lang="c#">
Line 172: Line 220:
=== Die In Air/ Liquid ===
=== Die In Air/ Liquid ===


Can be used for particles in water, which should disappear once they reach the surface.
This property is useful for particles in water, which should disappear once they reach the surface (die in liquid). Of course this can also be used the other way round (die in air).
 
 
 
{{Navbox/modding|Vintage Story}}

Revision as of 19:49, 7 May 2020

VintageStory offers a variety of different types of particles. This tutorial will explain you how to create simple particles 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.

Spawn particles

So let's spawn some 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 left to do is to set the position and spawn the particles into the world. I'm gonna use the OnHeldInteractStart and *Step method inside a custom made Item class (you can read more about this in the Collectibles Tutorial):

        public override void OnHeldInteractStart(ItemSlot slot, EntityAgent byEntity, BlockSelection blockSel, EntitySelection entitySel, ref EnumHandHandling handHandling)
        {
            handHandling = EnumHandHandling.Handled;
        }

        public override bool OnHeldInteractStep(float secondsUsed, ItemSlot slot, EntityAgent 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);

            return true;
        }

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

BasicParticles.png

Properties Overview

There are several things you can configure. Here is an overview which covers all of the 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:

Particle (equal position).png

If we now set addPos ...

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

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

Particle (differnt position).png

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):

Particles (equal velocity).gif

Life length

This property is pretty straight forward. A life length of one equals one second.

Particles will exist for one 200 milliseconds ...

    myParticles.lifeLength = 0.2F;

Particles (short life).gif


Particles will exist for one second ...

    myParticles.lifeLength = 1F;

Particles (long life).gif

Quantity

Determines how many particles will spawn.

    myParticles.minQuantity = 3;

This will spawn 3 particles each tick.

Particles (many).gif

Furthermore you can specify an additional quantity chance ...

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

This will spawn 0 to 100 particles per tick.

Particles (random many).png

Color

A color can be specified using ARGB (Alhpa, Red, Green, Blue). All values have a range of 0 to 255.

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

This will spawn red particles ...

Particles (red).gif

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

This will spawn particles with a random color ...

Particles (random colors).gif

Glow

This property allows you to define whether the particles will be visible in the dark or not ...

    myParticles.glowLevel = 20;

Particles (glowing).gif

    myParticles.glowLevel = 255;

Particles (glowing brightest).gif

Gravity

Gravity effect can not only be increase or decreased, ...

    myParticles.gravityEffect = 0.1F;

Particles (low gravity).gif

... but you can also disable it completely (using zero gravity) or invert it (particles will fly up).

Size

Again, you can specify a minimum size and an additional randomized size ...

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

Particles (random size).gif

Furthermore you can specify a SizeEvolve like so ...

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

Particles (growing size).gif

There are many EnumTransformFunctions you can play around with. Linear is the most basic one.

Model

There are two types of models. Cube (the one we used so far) and Quads:

    myParticles.model = EnumParticleModel.Quad;

Particles (quads).gif

Opacity

Quads support custom opacity. This allows you to make them transparent ...

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

Particles (opacity).gif

Similar to SizeEvolve you can add an OpacityEvolve ...

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

Particles (decreasing opacity).gif

Self Propelled

This property will make particles don't lose their velocity, even if they would collide with something, as soon as there is enough space they will continue to fly in the direction (with the same speed) ...

    myParticles.minVelocity = new Vec3f((float) (rand.NextDouble() - 0.5), 1f, (float) (rand.NextDouble() - 0.5));
    myParticles.SelfPropelled = true;

Particles (selfpropelled).gif

Die In Air/ Liquid

This property is useful for particles in water, which should disappear once they reach the surface (die in liquid). Of course this can also be used the other way round (die in air).


Icon Sign.png

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.