Ephemeral Particle System

Do you want particles in your game? Here’s a way to do it!

What do you mean by particles anyway?

A particle is a small object. In gaming jargon, a particle system is something that spawns lots of those small objects that last for a short period of time. It’s commonly used for effects like smoke and fire.

However, this is a powerful and robust tool - if you want to spawn some or a lot of something, and have it last a short time or forever, this likely has your needs covered.

This package is designed to be usable right out of the box with no programming experience, but for anyone looking to learn I tried to make the code especially readable, and for those who do know what they’re doing hopefully it is easy to extend and do whatever you want with it :slight_smile:


How to Acquire Package
  1. Go to the community tab.

  2. Search for Ephemeral Particle System. Heck, you don’t even have to type the full name in, even just rogue will get you there. Then, click the Install button on the one you see below, circled in blue. (It says Installed here because I’ve already done so)
    ephcompart

Congratulations! You’re now ready to use the package!

Getting Started

The heart of this package is the Particle Spawner script. To easily bring it into your project, use the Particle Spawner template. It is a Locator (a type of entity that doesn’t do anything in and of itself) with the script attached. You could otherwise attach the ParticleSpawner to whatever entity you like.
ephtemplate

Once you’ve done this, you can click on the Particle Spawner entity in the world tree and look at its properties. It might look like an overwhelming mix of things, if so, collapse all until you just see the basic categories:

Now let’s walk through each section and it’ll become much clearer!


Behavior

behavior

The behavior section controls the behavior of the particle spawner itself.

Spawn on Initialization: This controls whether or not the particle system will begin spawning things as soon as it enters the world (typically at the start of the game), or when you spawn it in. Without this enabled, you’ll have to hook this up to another script’s Event and call StartSpawning(). If you don’t understand that sentence, just leave it enabled. We’ll cover more advanced uses later!

Particles per Second: How many particles it spawns every second. To create a more organic effect, it’s often desirable to have this change from second to second. Like most fields in this script, the number you put in the left will be the minimum amount spawned every second, and the right will be the maximum amount. Right now it’s set to spawn 0 a second. That’s not going to be very useful. You set the two values as identical, and it’ll always spawn that many each second. Or you can put in a random range.

Limit Particles: Sometimes you only want to spawn a certain number of things, instead of spawning infinitely. This means the system will only run until its spawned its maximum number of things, and then it won’t spawn any more. You can also randomly assign the desired amount. Best to keep it to whole, positive numbers, or else you’ll likely encounter errors.

Spawn in Waves: Instead of spawning continuously, the system will only spawn a limited amount before taking a break and starting again. You can randomize these values.

Particles

particles

The particle section controls which “particles” spawn. A particle in this instance is just any template. Typically you’ll want it to be something visible, likely a mesh, effect, or voxel mesh, but any template can work!

We’ll discuss making your own particles later.

Particles to Spawn: Here you put the templates you want to spawn. All arrays below this correspond to this array - the first item in any array will be the default and apply to the first particle here, the second item in any array will apply only to the second particle here, the eighth will correspond to the eighth, etc… You get it. (If you don’t get it please ask so I can find a better way to explain!)

Equal Spawn Chance: Does, as they say, what it says on the tin. If enabled, there’s an equal chance for every particle to spawn. Otherwise, if it’s disabled you can adjust the spawn rate per particle

Particle Lifetime: This controls how long the particle stays active before disappearing. You can set this as a random range so things look more organic.

Initial Placement

initial

This section has three thing sit can do to make your particles spawn differently. With none of the options, every particle will spawn in the same place (wherever you put your locator), with the same rotation, and at a scale of 1 (for meshes only).

placemement

If you enable them all, you’ll see for Position you can alter the Offset in each direction. Leaving the arrays empty likely will cause an error.

For Rotation it’s the same thing, you can alter pitch yaw and roll.

For Scale, which currently applies just to meshes, by default it’ll just randomly pick one number and apply it to all three dimensions of scale. If you’d like to let the mesh get out of proportion, you can enable disproportionate scaling and alter them individually.

Velocity

image

If you’d like to have this script make your particles move, this optional section enables a very simple movement. You can attach your own script to a particle to move it instead.

Rotation

image

If you’d like to have this script make your particles rotate over time, this optional section enables two different types of rotation. Angular velocity works more intuitively, but (at least to my knowledge) rotating pitch doesn’t work properly. Timeline Rotation is a bit of a hacky implementation, but you want to use small numbers for that one. You can attach your own script to a particle to rotate it instead.

Object Pooling

image

This section is pretty technical and related just to performance, basically. Object Pooling, in game design, is a pattern where instead of creating objects over and over again and then deleting them, we instead recycle and re-use them, saving on performance.

Spawn Toggles toggle various attributes when the object activates and deactivates. So Toggle Visibility will make it visible while active, then when its lifetime is complete, it becomes invisible. Toggle Active works the same way for objects like Effects that use active. You can pretty safely leave these enabled unless there’s a desired behavior you have that’s different.

The rest of the pooling section is relatively self explanatory and can be left alone if things behave the way you want them to. The starting pool is the amount of objects that the Particle Spawner creates when it’s created, then the Max Pool Size is the maximum amount of objects the pool will allow before it starts to check for Culling unused ones. Every Cull Check Interval, if an object has been unused for the Cull Time, it’ll get deleted to free up resources/space. Feel free to ask questions if you need more guidance on that!


Creating a Template

Just in case you’re unsure, here’s how you make a template.

Let’s say you want to use lobsters for your particle. You can find the lobster in the mesh menu (highlighted on the left). Then, click and drag it into the scene, or into your world tree, dealer’s choice.

Look at the cute lil friend, who wouldn’t want to see more of 'em?

It’s very easy to make him a template to use with this script. In fact, we’ve already done most of the hard work!

With your lobster buddy selected, click Template and then Create New Template

templatename

Give your template a name. It’s good practice to name things practically, but I won’t tell on you if you just choose names that amuse you.

That’s it!

image

Now you can see our template is saved.

Plug it in to a particle spawner, nice and easy, and…

Glorious!

Using Your Own Velocity/Rotation Scripts

Every time an object is pulled from the pool to spawn, or returned to it, the SpawnToggles function is called. If the object has a script attached that has a function named OnSpawn(something) or OnComplete(something) (depending if it’s spawning or returning to the pool), that calls something() inside of it, then the particle system won’t control many of the aspects of the object. Instead, you can define what will happen yourself in that script.

Included in the package is an EphemeralParticle script. Simply modify it, or copy and paste it, and it’ll be all set up for you to define your own things that happen when spawning. Attach the script to the template you want to use as your particle, and you’re good to go.

The script looks like this:

local EphemeralParticle = {}

EphemeralParticle.Properties = {
	
}

function EphemeralParticle:Init()
end


function EphemeralParticle:OnSpawn(success)
--Use this space to do something like defining your own movement or rotation functions.
success()
end

function EphemeralParticle:OnComplete(success)
--Use this space to do something like ending your movement or rotation functions.
success()
end


return EphemeralParticle

You can simply start a new script based on this, copy and paste it in, and rename it and go!


Please feel free to ask any questions here or message me in discord! (ephemerald#2661)