oss/luanti
oss/luanti
1
0
Fork 0
mirror of https://github.com/luanti-org/luanti.git synced 2025-08-06 17:41:04 +00:00
Code Wiki Activity

Fix and improve particle(spawner) documentation (#14804)

Browse source
This commit is contained in:
grorp 2024-07-06 18:02:31 +02:00 • committed by GitHub
parent fcb4f258f5
commit 3de42f56c5
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 124 additions and 36 deletions
Download patch file Download diff file Expand all files Collapse all files

74
doc/lua_api.md
View file

@ -10711,6 +10711,11 @@ Used by `minetest.add_particle`.
drag = {x=0, y=0, z=0},
-- v5.6.0 and later: Optional drag value, consult the following section
-- Note: Only a vector is supported here. Alternative forms like a single
-- number are not supported.
jitter = {min = ..., max = ..., bias = 0},
-- v5.6.0 and later: Optional jitter range, consult the following section
bounce = {min = ..., max = ..., bias = 0},
-- v5.6.0 and later: Optional bounce range, consult the following section
@ -10736,7 +10741,10 @@ will be ignored.
```lua
{
-- Common fields (same name and meaning in both new and legacy syntax)
-------------------
-- Common fields --
-------------------
-- (same name and meaning in both new and legacy syntax)
amount = 1,
-- Number of particles spawned over the time period `time`.
@ -10768,6 +10776,8 @@ will be ignored.
texture = "image.png",
-- The texture of the particle
-- v5.6.0 and later: also supports the table format described in the
-- following section.
playername = "singleplayer",
-- Optional, if specified spawns particles only on the player's client
@ -10793,7 +10803,9 @@ will be ignored.
-- particle texture is picked.
-- Otherwise, the default behavior is used. (currently: any random tile)
-- Legacy definition fields
-------------------
-- Legacy fields --
-------------------
minpos = {x=0, y=0, z=0},
maxpos = {x=0, y=0, z=0},
@ -10921,32 +10933,46 @@ All of the properties that can be defined in this way are listed in the next
section, along with the datatypes they accept.
#### List of particlespawner properties
All of the properties in this list can be animated with `*_tween` tables
unless otherwise specified. For example, `jitter` can be tweened by setting
a `jitter_tween` table instead of (or in addition to) a `jitter` table/value.
All properties in this list of type "vec3 range", "float range" or "vec3" can
be animated with `*_tween` tables. For example, `jitter` can be tweened by
setting a `jitter_tween` table instead of (or in addition to) a `jitter`
table/value.
In this section, a float range is a table defined as so: { min = A, max = B }
A and B are your supplemented values. For a vec3 range this means they are vectors.
Types used are defined in the previous section.
* vec3 range `pos`: the position at which particles can appear
* vec3 range `vel`: the initial velocity of the particle
* vec3 range `acc`: the direction and speed with which the particle
accelerates
* vec3 range `size`: scales the visual size of the particle texture.
if `node` is set, this can be set to 0 to spawn randomly-sized particles
(just like actual node dig particles).
* vec3 range `jitter`: offsets the velocity of each particle by a random
amount within the specified range each frame. used to create Brownian motion.
* vec3 range `drag`: the amount by which absolute particle velocity along
each axis is decreased per second. a value of 1.0 means that the particle
will be slowed to a stop over the space of a second; a value of -1.0 means
that the particle speed will be doubled every second. to avoid interfering
with gravity provided by `acc`, a drag vector like `vector.new(1,0,1)` can
be used instead of a uniform value.
* float range `bounce`: how bouncy the particles are when `collisiondetection`
is turned on. values less than or equal to `0` turn off particle bounce;
`1` makes the particles bounce without losing any velocity, and `2` makes
them double their velocity with every bounce. `bounce` is not bounded but
values much larger than `1.0` probably aren't very useful.
* float range `exptime`: the number of seconds after which the particle
disappears.
* table `attract`: sets the birth orientation of particles relative to various
shapes defined in world coordinate space. this is an alternative means of
setting the velocity which allows particles to emerge from or enter into
@ -10954,8 +10980,10 @@ Types used are defined in the previous section.
velocity values within a range. the velocity calculated by this method will
be **added** to that specified by `vel` if `vel` is also set, so in most
cases **`vel` should be set to 0**. `attract` has the fields:
* string `kind`: selects the kind of shape towards which the particles will
be oriented. it must have one of the following values:
* `"none"`: no attractor is set and the `attractor` table is ignored
* `"point"`: the particles are attracted to a specific point in space.
use this also if you want a sphere-like effect, in combination with
@ -10966,25 +10994,32 @@ Types used are defined in the previous section.
* `"plane"`: the particles are attracted to an (infinite) plane on whose
surface `origin` designates a point in world coordinate space. use this
for e.g. particles entering or emerging from a portal.
* float range `strength`: the speed with which particles will move towards
`attractor`. If negative, the particles will instead move away from that
point.
* vec3 `origin`: the origin point of the shape towards which particles will
initially be oriented. functions as an offset if `origin_attached` is also
set.
* vec3 `direction`: sets the direction in which the attractor shape faces. for
lines, this sets the angle of the line; e.g. a vector of (0,1,0) will
create a vertical line that passes through `origin`. for planes, `direction`
is the surface normal of an infinite plane on whose surface `origin` is
a point. functions as an offset if `direction_attached` is also set.
* entity `origin_attached`: allows the origin to be specified as an offset
from the position of an entity rather than a coordinate in world space.
* entity `direction_attached`: allows the direction to be specified as an offset
* ObjectRef `origin_attached`: allows the origin to be specified as an offset
from the position of an entity rather than a coordinate in world space.
* ObjectRef `direction_attached`: allows the direction to be specified as an
offset from the position of an entity rather than a coordinate in world space.
* bool `die_on_contact`: if true, the particles' lifetimes are adjusted so
that they will die as they cross the attractor threshold. this behavior
is the default but is undesirable for some kinds of animations; set it to
false to allow particles to live out their natural lives.
* vec3 range `radius`: if set, particles will be arranged in a sphere around
`pos`. A constant can be used to create a spherical shell of particles, a
vector to create an ovoid shell, and a range to create a volume; e.g.
@ -10996,9 +11031,10 @@ Types used are defined in the previous section.
### Textures
In versions before v5.6.0, particlespawner textures could only be specified as a single
texture string. After v5.6.0, textures can now be specified as a table as well. This
table contains options that allow simple animations to be applied to the texture.
In versions before v5.6.0, particle/particlespawner textures could only be
specified as a single texture string. After v5.6.0, textures can now be
specified as a table as well. This table contains options that allow simple
animations to be applied to the texture.
```lua
texture = {
@ -11053,18 +11089,18 @@ texture = {
}
```
Instead of setting a single texture definition, it is also possible to set a
`texpool` property. A `texpool` consists of a list of possible particle textures.
Every time a particle is spawned, the engine will pick a texture at random from
the `texpool` and assign it as that particle's texture. You can also specify a
`texture` in addition to a `texpool`; the `texture` value will be ignored on newer
clients but will be sent to older (pre-v5.6.0) clients that do not implement
texpools.
For particlespawners, it is also possible to set the `texpool` property instead
of a single texture definition. A `texpool` consists of a list of possible
particle textures. Every time a particle is spawned, the engine will pick a
texture at random from the `texpool` and assign it as that particle's texture.
You can also specify a `texture` in addition to a `texpool`; the `texture`
value will be ignored on newer clients but will be sent to older (pre-v5.6.0)
clients that do not implement texpools.
```lua
texpool = {
"mymod_particle_texture.png";
{ name = "mymod_spark.png", fade = "out" },
{ name = "mymod_spark.png", alpha_tween = {1, 0} },
{
name = "mymod_dust.png",
alpha = 0.3,