diff --git a/doc/lua_api.md b/doc/lua_api.md index 5709109ab..efe05e5d9 100644 --- a/doc/lua_api.md +++ b/doc/lua_api.md @@ -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, diff --git a/src/network/networkprotocol.h b/src/network/networkprotocol.h index 4d9900ea0..e3618042f 100644 --- a/src/network/networkprotocol.h +++ b/src/network/networkprotocol.h @@ -502,22 +502,50 @@ enum ToClientCommand : u16 TOCLIENT_SPAWN_PARTICLE = 0x46, /* - -- struct range { T min, T max, f32 bias }; + using range = RangedParameter { + T min, max + f32 bias + } + using tween = TweenedParameter { + 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 bounce + range jitter + range bounce + + texture { + u8 flags (ParticleTextureFlags) + -- bit 0: animated + -- next bits: blend mode (BlendMode) + tween alpha + tween scale + } */ TOCLIENT_ADD_PARTICLESPAWNER = 0x47, @@ -536,7 +564,7 @@ enum ToClientCommand : u16 u16 amount f32 spawntime if PROTOCOL_VERSION >= 42 { - tween pos, vel, acc, exptime, size + tween> 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 vel_end range acc_end + range exptime_end + range size_end + } + + texture { + u8 flags (ParticleTextureFlags) + -- bit 0: animated + -- next bits: blend mode (BlendMode) + tween alpha + tween scale + + if (flags.animated) + TileAnimation animation } tween> drag @@ -597,24 +647,26 @@ enum ToClientCommand : u16 u8 spawner_flags bit 1: attractor_kill (particles dies on contact) if attraction_mode > point { - tween attractor_angle - u16 attractor_origin_attachment_object_id + tween attractor_direction + u16 attractor_direction_attachment_object_id } } tween> radius - tween> 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 alpha tween scale - if flags.animated { + + u32 len + u8[len] texture + + if (flags.animated) TileAnimation animation - } } */