Luawe All pages

Particles that bounce

A Particles child lets particles go (the page Particles shows how to set them up): sparks, smoke, rain, confetti. By themselves they fly through everything. Give them collisions and they bounce off walls, stay on the path, or settle where they land. A script can hear each time one of them hits something or touches the character, and can sweep them all away at once.

This page shows what the editor's Collisions rows do, the two events a script hears, and how to clear particles. Every script here can be put into an empty level and tried with F5.

What they bounce off

In the editor, pick a thing with a Particles child. Its Collisions section has four switches. Any of them can be on together.

SwitchThe particles...Script name
Waterstay on the path: they bounce off where it meets the waterparticles.collideWater
Pathstay on the water: they bounce off the edges of the pathparticles.collidePath
Blocksbounce off everything that hurts the character, and solid objectsparticles.collideBlocks
Custombounce off the things you pick in the list under itparticles.collideCustom

The Custom list picks things the way a Path mask picks its parts: a group (everything in it), one thing, or every thing of a name. An object counts by its hitbox, floor by its rectangle and a text by its box, wherever they are at that moment: moved, turned or keyed. Unlike a mask's parts, the picked things stay just as they were.

What they do when they hit

On a hit says what a particle does when it hits something it collides with:

On a hitWhat happensGood for
Bounceit bounces offdebris, balls, sparks
Stickit stays where it hit, for the rest of its lifesnow that settles, paint
Vanishit goes at oncerain that splashes

Bounce is how much of its speed a particle keeps when it bounces. 1 keeps all of it, 0.1 keeps a tenth, 0 stops it dead. The editor's slider goes from 0 to 1. A script can go further: above 1 a particle speeds up at every bounce, and below 0 it goes back the way it came.

local ball = world.Ball
ball.particles.bounce = 1.5 -- faster after every bounce

Drag, in the Movement rows, slows particles down as they fly. With a little drag and a bounce under 1, debris flies, bounces a few times and comes to a stop.

Their hitbox

The Hitbox rows work like an object's: Size (times the particle's size, so it shrinks and grows with the particle), Shape (Box or Circle), Padding and Offset. It turns with the particle. It is what bumps into things, and what touches the character.

In a script they have the names a thing's own hitbox has: hitbox is the size, and hitboxShape, hitboxPadX, hitboxPadY, hitboxX and hitboxY are the others.

local ball = world.Ball
ball.particles.hitbox = 0.5
ball.particles.hitboxShape = cat.HitboxShape.circle
ball.particles.hitboxPadX = 0.1
print(ball.particles.hitboxShape)

Hearing a hit

thing.particleHit is an event that happens when one of the thing's particles hits something it collides with. The function gets a hit: the same kind of table world:raycast gives, with the particle's speed in it.

local sparks = world.Sparks

sparks.particleHit:connect(function(hit)
    print(`a spark hit at {hit.x}, {hit.y}, going {hit.velocityX} across`)
    if hit.thing then
        print(`it hit {hit.thing.name}`)
    end
end)
In hitMeans
x, yWhere the particle was when it hit
velocityX, velocityYHow fast it went as it hit, in tiles a beat
normalX, normalYThe way the side it hit faces
thingThe thing it hit, or nil at the water's or the path's edge
kindWhat it was: cat.Collision.water, cat.Collision.path, cat.Collision.blocks or cat.Collision.custom

A particle that comes in very slowly, as one lying on the floor does, slides along instead of bouncing, and is not heard.

Hearing a touch

thing.particleTouched happens when one of the thing's particles starts to touch the character. Each particle is heard once, until it stops touching. This works for any particles, with or without collisions.

local rain = world.Rain
local drops = 0

rain.particleTouched:connect(function(hit)
    drops += 1
    print(`{drops} drops so far`)
end)

Its hit has x, y and the particle's speed. normalX, normalY point from the character to the particle, and thing and kind are nil.

Clearing particles

thing:clearParticles() takes every particle the thing has out away at once. Particles it lets go after that fly as always.

local smoke = world.Smoke
wait(4)
smoke:clearParticles()

The Particles node can do the same: set it to clear each time it turns on. Unlike its other two settings, it takes nothing over: the particles still flow by themselves.

A wall that breaks into pieces

All of it together: a wall that bursts into pieces when the character touches it, pieces that bounce off the blocks and the water's edge, slow to a stop, and are swept away at the end.

local wall = world.Wall
wall:addChild(cat.Child.particles, {
    manual = true, lifetime = range2.new(5.5, 6.5), direction = 0, spread = 70,
    speed = range2.new(5, 11), drag = 1.2, rotationSpeed = range2.new(-360, 360),
    collideWater = true, collideBlocks = true, bounce = 0.6,
})

wall.touched:wait()  -- the script stops here until the character touches the wall
wall:emit(40)
wall.alpha = 0       -- the wall hides, its pieces stay
wait(8)
wall:clearParticles()

What to notice:

  • manual = true keeps the wall from letting pieces go by itself. wall:emit(40) lets 40 go at once.
  • lifetime, speed and rotationSpeed are ranges: each piece takes its own number between the two ends.
  • Hiding the wall (wall.alpha = 0) does not hide its particles.
  • Try bounce = 1 and drag = 0: the pieces never stop. Try onHit = cat.ParticleHit.stick: they stay where they land.

The whole script, with a room built for it, is A wall that breaks into pieces. In the editor it is under Logic, Scripts, Try an example.

Good to know

  • Particles that collide cost more than ones that don't: each one is worked out step by step. Keep Most at once as low as looks right.
  • Particles that collide look the same in the editor at any beat, in a test play from the middle, and after a checkpoint.
  • Particles of a text pinned to the screen never collide.
  • The hits of particles are worked out 48 times a beat; what they bounce off is looked at 16 times a beat. A block that moves very fast can let a particle through.