Particles (The Chickadee Game Toolkit)

From 279f17ac0e1b3d019c2b294098e834d249376686 Mon Sep 17 00:00:00 2001 From: David Thompson Date: Tue, 4 Jun 2019 20:49:16 -0400 Subject: Update chickadee manual. --- manuals/chickadee/Particles.html | 263 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 263 insertions(+) create mode 100644 manuals/chickadee/Particles.html (limited to 'manuals/chickadee/Particles.html') diff --git a/manuals/chickadee/Particles.html b/manuals/chickadee/Particles.html new file mode 100644 index 0000000..35a6b61 --- /dev/null +++ b/manuals/chickadee/Particles.html @@ -0,0 +1,263 @@ + + + + + + +Particles (The Chickadee Game Toolkit) + + + + + + + + + + + + + + + + + + + + + +

+ +

2.3.6 Particles

+ +

Effects like smoke, fire, sparks, etc. are often achieved by animating +lots of little, short-lived sprites known as “particles”. In fact, +all of these effects, and more, can be accomplished by turning a few +configuration knobs in a “particle system”. A particle system takes +care of managing the many miniscule moving morsels so the developer +can quickly produce an effect and move on with their life. The +(chickadee render particles) module provides an API for +manipulating particle systems. +

Below is an example of a very simple particle system that utilizes +nearly all of the default configuration settings: +

(use-modules (chickadee render particles))
+(define texture (load-image "particle.png"))
+(define particles (make-particles 2000 #:texture texture))
+

+ +

In order to put particles into a particle system, a particle +“emitter” is needed. Emitters know where to spawn new particles, +how many of them to spawn, and for how long they should do it. +

Below is an example of an emitter that spawns 16 particles per frame +at the coordinates (320, 240): +

(use-modules (chickadee math vector))
+(define emitter (make-particle-emitter (vec2 320.0 240.0) 16))
+(add-particle-emitter particles emitter)
+

+ +

To see all of the tweakable knobs and switches, read on! +

Procedure: make-particles capacity [#:blend-mode alpha] [#:color white] [#:end-color transparent] [#:texture] [#:animation-rows 1] [#:animation-columns 1] [#:width] [#:height] [#:speed-range (vec2 0.1 1.0)] [#:acceleration-range (vec2 0.0 0.1)] [#:direction-range (vec2 0 (* 2 pi))] [#:lifetime 30] [#:sort]

Return a new particle system that may contain up to capacity +particles. Achieving the desired particle effect involves tweaking +the following keyword arguments as needed: +

- blend-mode: Pixel blending mode. alpha by default. +(see Blending for more about blend modes). +

- start-color: The tint color of the particle at the beginning of its +life. White by default. +

- end-color: The tint color of the particle at the end of of its +life. Completely transparent by default for a fade-out effect. The +color in the middle of a particle’s life will be an interpolation of +start-color and end-color. +

- texture: The texture applied to the particles. The texture +may be subdivided into many animation frames. +

- animation-rows: How many animation frame rows there are in the +texture. Default is 1. +

- animation-columns: How many animation frame columns there are +in the texture. Default is 1. +

- width: The width of each particle. By default, the width of +an animation frame (in pixels) is used. +

- height: The height of each particle. By default, the height +of an animation frame (in pixels) is used. +

- speed-range: A 2D vector containing the min and max particle +speed. Each particle will have a speed chosen at random from this +range. By default, speed ranges from 0.1 to 1.0. +

- acceleration-range: A 2D vector containing the min and max +particle acceleration. Each particle will have an acceleration chosen +at random from this range. By default, acceleration ranges from 0.0 +to 0.1. +

- direction-range: A 2D vector containing the min and max +particle direction as an angle in radians. Each particle will have a +direction chosen at random from this range. By default, the range +covers all possible angles. +

- lifetime: How long each particle lives, measured in +updates. 30 by default. +

- sort: youngest if youngest particle should be drawn +last or oldest for the reverse. By default, no sorting is +applied at all. +

+ +

Procedure: particles? obj: Return #t if obj is a particle system. +

+ +

Procedure: update-particles particles: Advance the simulation of particles. +

+ +

Procedure: draw-particles particles: Render particles. +

+ +

Procedure: draw-particles* particles matrix: Render particles with matrix applied. +

+ +

Procedure: make-particle-emitter spawn-area rate [duration]: +
Return a new particle emitter that spawns rate particles per +frame within spawn-area (a rectangle or 2D vector) for +duration frames. If duration is not specified, the +emitter will spawn particles indefinitely. +

+ +

Procedure: particle-emitter? obj: Return #t if obj is a particle emitter. +

+ +

Procedure: particle-emitter-spawn-area emitter: Return the spawn area for emitter. +

+ +

Procedure: particle-emitter-rate emitter: Return the number of particles that emitter will spawn per +frame. +

+ +

Procedure: particle-emitter-life emitter: Return the number of frames remaining in emitter’s lifespan. +

+ +

Procedure: particle-emitter-done? emitter: Return #t if emitter has finished spawning particlces. +

+ +

Procedure: add-particle-emitter particles emitter: Add emitter to particles. +

+ +

Procedure: remove-particle-emitter particles emitter: Remove emitter to particles +

+ +

+ + + + + + -- cgit v1.2.3