mirror of
https://github.com/minetest/minetest.git
synced 2024-11-08 08:43:47 +01:00
Fix and improve particle(spawner) documentation (#14804)
This commit is contained in:
grorp
GitHub
parent
fcb4f258f5
commit
3de42f56c5
@ -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,
|
||||
|
||||
@ -502,22 +502,50 @@ enum ToClientCommand : u16
|
||||
|
||||
TOCLIENT_SPAWN_PARTICLE = 0x46,
|
||||
/*
|
||||
-- struct range<T> { T min, T max, f32 bias };
|
||||
using range<T> = RangedParameter<T> {
|
||||
T min, max
|
||||
f32 bias
|
||||
}
|
||||
using tween<T> = TweenedParameter<T> {
|
||||
u8 style
|
||||
u16 reps
|
||||
f32 beginning
|
||||
T start, end
|
||||
}
|
||||
|
||||
v3f pos
|
||||
v3f velocity
|
||||
v3f acceleration
|
||||
f32 expirationtime
|
||||
f32 size
|
||||
u8 bool collisiondetection
|
||||
|
||||
u32 len
|
||||
u8[len] texture
|
||||
|
||||
u8 bool vertical
|
||||
u8 collision_removal
|
||||
u8 bool collision_removal
|
||||
|
||||
TileAnimation animation
|
||||
|
||||
u8 glow
|
||||
u8 object_collision
|
||||
u8 bool object_collision
|
||||
|
||||
u16 node_param0
|
||||
u8 node_param2
|
||||
u8 node_tile
|
||||
|
||||
v3f drag
|
||||
range<v3f> bounce
|
||||
range<v3f> jitter
|
||||
range<f32> bounce
|
||||
|
||||
texture {
|
||||
u8 flags (ParticleTextureFlags)
|
||||
-- bit 0: animated
|
||||
-- next bits: blend mode (BlendMode)
|
||||
tween<f32> alpha
|
||||
tween<v2f> scale
|
||||
}
|
||||
*/
|
||||
|
||||
TOCLIENT_ADD_PARTICLESPAWNER = 0x47,
|
||||
@ -536,7 +564,7 @@ enum ToClientCommand : u16
|
||||
u16 amount
|
||||
f32 spawntime
|
||||
if PROTOCOL_VERSION >= 42 {
|
||||
tween<T> pos, vel, acc, exptime, size
|
||||
tween<range<T>> pos, vel, acc, exptime, size
|
||||
} else {
|
||||
v3f minpos
|
||||
v3f maxpos
|
||||
@ -550,14 +578,23 @@ enum ToClientCommand : u16
|
||||
f32 maxsize
|
||||
}
|
||||
u8 bool collisiondetection
|
||||
|
||||
u32 len
|
||||
u8[len] texture
|
||||
|
||||
u32 spawner_id
|
||||
u8 bool vertical
|
||||
u8 collision_removal
|
||||
u32 id
|
||||
u8 bool collision_removal
|
||||
u32 attached_id
|
||||
|
||||
TileAnimation animation
|
||||
|
||||
u8 glow
|
||||
u8 object_collision
|
||||
u8 bool object_collision
|
||||
|
||||
u16 node_param0
|
||||
u8 node_param2
|
||||
u8 node_tile
|
||||
|
||||
if PROTOCOL_VERSION < 42 {
|
||||
f32 pos_start_bias
|
||||
@ -572,6 +609,19 @@ enum ToClientCommand : u16
|
||||
-- f32 pos_end_bias
|
||||
range<v3f> vel_end
|
||||
range<v3f> acc_end
|
||||
range<f32> exptime_end
|
||||
range<f32> size_end
|
||||
}
|
||||
|
||||
texture {
|
||||
u8 flags (ParticleTextureFlags)
|
||||
-- bit 0: animated
|
||||
-- next bits: blend mode (BlendMode)
|
||||
tween<f32> alpha
|
||||
tween<v2f> scale
|
||||
|
||||
if (flags.animated)
|
||||
TileAnimation animation
|
||||
}
|
||||
|
||||
tween<range<v3f>> drag
|
||||
@ -597,24 +647,26 @@ enum ToClientCommand : u16
|
||||
u8 spawner_flags
|
||||
bit 1: attractor_kill (particles dies on contact)
|
||||
if attraction_mode > point {
|
||||
tween<v3f> attractor_angle
|
||||
u16 attractor_origin_attachment_object_id
|
||||
tween<v3f> attractor_direction
|
||||
u16 attractor_direction_attachment_object_id
|
||||
}
|
||||
}
|
||||
|
||||
tween<range<v3f>> radius
|
||||
tween<range<v3f>> drag
|
||||
|
||||
u16 texpool_sz
|
||||
texpool_sz.times {
|
||||
u8 flags
|
||||
u16 texpool_size
|
||||
texpool_size.times {
|
||||
u8 flags (ParticleTextureFlags)
|
||||
-- bit 0: animated
|
||||
-- other bits free & ignored as of proto v40
|
||||
-- next bits: blend mode (BlendMode)
|
||||
tween<f32> alpha
|
||||
tween<v2f> scale
|
||||
if flags.animated {
|
||||
|
||||
u32 len
|
||||
u8[len] texture
|
||||
|
||||
if (flags.animated)
|
||||
TileAnimation animation
|
||||
}
|
||||
}
|
||||
|
||||
*/
|
||||
|
||||
Loading…
Reference in New Issue
Block a user