diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/lua_api.txt | 189 |
1 files changed, 186 insertions, 3 deletions
diff --git a/doc/lua_api.txt b/doc/lua_api.txt index 7d552c980..3b3f17634 100644 --- a/doc/lua_api.txt +++ b/doc/lua_api.txt @@ -414,6 +414,119 @@ the word "`alpha`", then each texture pixel will contain the RGB of `<color>` and the alpha of `<color>` multiplied by the alpha of the texture pixel. +Particle blend +-------------- +Blend function is defined by integer number. +There is a huge number of acceptable blend modificators. +Colour of a resulting pixel calculated using formulae: + + red = source_red * source_factor + destination_red * destination_factor + +and so on for every channel. + +Here is a some examples: + +Default value: + + material_type_param = 0, + +Use this value to disable blending. Texture will be applied to existing pixels +using alpha channel of it. Its recomended to use 1-bit alpha +in that case. This value will leave z-buffer writeable. + +Additive blend: + + material_type_param = 12641, + +Source = src_alpha, destination = one, alpha source is a texture and +vertex_color, modulate_1x. +Black color is completely transparent, white color is completely opaque. +Alpha channel still used to calculate result color, but not nessesary. +'destination = one' means that resulting color will be calculated using +overwritten pixels values. +For example with color of source (our texture) RGBA = (0,192,255,63) +"blue-cyan", 1/4 opaque. +and already rendered pixel color (40,192,0) "dark lime green" we will get color: + +R = source_red(0) * source_factor(src_alpha=63/255) + + destination_red(40) * destination_factor(one) = + 0 * 63/255 + 40 * 1 = 40 + +G = 192 * 63/255 + 192 * 1 = 239 +B = 255 * 63/255 + 0 * 1 = 63 + +Result: (40,239,63), "green" (a kind of). +Note, if you made a texture with some kind of shape with colour 662211h +it will appear dark red with a single particle, then yellow with a +several of them and white if player looking thru a lot of them. With +this you could made a nice-looking fire. + +Substractive blend: + + material_type_param = 12548, + +Source = zero, destination = src_color, alpha source is a texture and +vertex_color, modulate_1x. +Texture darkness act like an alpha channel. +Black color is completely opaque, white color is completely transparent. +'destination = src_color' means that destination in multiplied by +a source values. 'source = zero' means that source values ignored +(multiplied by 0). + +Invert blend: + + material_type_param = 12597, + +Source = one_minus_dst_color, destination = one_minus_src_alpha, alpha source +is a texture and vertex_color, modulate_1x. +Pixels invert color if source color value is big enough. If not, they just +black. +'destination = one_minus_src_alpha' means, that effect is masked by a +source alpha channel. + +You can design and use your own blend using those enum values and function +'minetest.pack_texture_blend_func'. Returned value of a function is +your 'material_type_param'. + +A values in a brackets is a multiplicators of a red, green, blue +and alpha channels respectively. + +* 'minetest.ebf': global table, containing blend factor enum values. Such as: + * zero = 0 -- src & dest (0, 0, 0, 0) + * one = 1 -- src & dest (1, 1, 1, 1) + * dst_color = 2 -- src (destR, destG, destB, destA) + * one_minus_dst_color = 3 -- src (1-destR, 1-destG, 1-destB, 1-destA) + * src_color = 4 -- dest (srcR, srcG, srcB, srcA) + * one_minus_src_color = 5 -- dest (1-srcR, 1-srcG, 1-srcB, 1-srcA) + * src_alpha = 6 -- src & dest (srcA, srcA, srcA, srcA) + * one_minus_src_alpha = 7 -- src & dest (1-srcA, 1-srcA, 1-srcA, 1-srcA) + * dst_alpha = 8 -- src & dest (destA, destA, destA, destA) + * one_minus_dst_alpha = 9 -- src & dest (1-destA, 1-destA, 1-destA, 1-destA) + * src_alpha_saturate = 10 -- src (min(srcA, 1-destA), idem, ...) + +* 'minetest.emfn': global table, containing modulate enum values. + * Multiply the components of the arguments, and shift the products to the + * left by x bits for brightening. Contain: + * modulate_1x = 1 -- no bit shift + * modulate_2x = 2 -- 1 bits shift + * modulate_4x = 4 -- 2 bits shift + +'modulate_4x' is quite useful when you want to make additive blend stronger +with a lower amount of particles. + +* 'minetest.eas': global table, containing alpha source enum values. Such as: + * none = 0 -- do not use alpha. + * vertex_color = 1 -- use vertex color alpha. + * texture = 2 -- use texture alpha. + +You can use both 'vertex_color' and 'texture' source by using value 3. + +* 'minetest.pack_texture_blend_func(srcFact, dstFact, modulate, alphaSource)': return integer + * Pack texture blend funcion variable. Depending from that variable blend + * function will be applied in time of a render poligons with selected material. + * Therefore resulting pixel will be 'source * srcFact + destination * dstFact' + * Use result of this function as 'material_type_param'. + Sounds ------ Only Ogg Vorbis files are supported. @@ -3650,7 +3763,7 @@ Definition tables ### Tile definition * `"image.png"` -* `{name="image.png", animation={Tile Animation definition}}` +* `{name="image.png", animation={Animation definition}}` * `{name="image.png", backface_culling=bool, tileable_vertical=bool, tileable_horizontal=bool}` * backface culling enabled by default for most nodes @@ -3661,8 +3774,50 @@ Definition tables * deprecated, yet still supported field names: * `image` (name) -### Tile animation definition -* `{type="vertical_frames", aspect_w=16, aspect_h=16, length=3.0}` +### Animation definition + +#### Node animation, particle and particle spawners +* `{ type="vertical_frames", + aspect_w=16, + -- ^ specify width of a picture in pixels. + aspect_h=16, + -- ^ specify height of a frame in pixels. + length=3.0 + -- ^ specify full loop length. + first_frame = 0, -- <- only for particles, use + min_first_frame = 0, -- <- for particle spawners + max_first_frame = 0, + loop_animation = true, -- <- only for particles and particle spawners + -- specify if animation should start from beginning after last frame. +}` + +#### Particle and particle spawners only +* `{ + type="2d_animation_sheet", -- <- only for particles and particle spawners + vertical_frame_num = 1, + horizontal_frame_num = 1, + -- ^ specify amount of frames in texture. + -- Can be used both for animation or for texture transform + -- together with first_frame variable. + -- A animation texture separated on equal parts of frames, + -- by horizontal and vertical numbers. For example with + -- vertical_frame_num = 4 and horizontal_frame_num = 3 we got + -- 4*3 = 12 frames in total. Animation sequence start from + -- left top frame and go on to the right until reach end of + -- row. Next row also start from left frame. + first_frame = 0, -- <- only for particles, use + min_first_frame = 0, -- <- for particle spawners + max_first_frame = 0, + -- ^ specify first frame to start animation. + frame_length = -1, + -- ^ specify length of a frame in seconds. Negative and zero values + -- disable animation. A sequence with vertical_frame_num = 4 and + -- horizontal_frame_num = 3, first_frame = 4 and frame_length = 0.1 + -- will end in (4*3-4)*0.1 = 0.8 seconds. + loop_animation = true, + -- specify if animation should start from beginning after last frame. +}` + * All settings are optional. Default values is located in this example. ### Node definition (`register_node`) @@ -4117,6 +4272,20 @@ The Biome API is still in an experimental phase and subject to change. -- ^ Uses texture (string) playername = "singleplayer" -- ^ optional, if specified spawns particle only on the player's client + material_type_param = 12641, + -- ^ optional, if specified spawns particle with + -- specified material type param and disable z-buffer. + -- Some examples: + -- Default value: 0, + -- Additive blend: 12641, + -- Substractive blend: 12548, + -- Invert blend: 12597, + -- See also "Particle blend". + animation = {Animation definition}, + -- ^ see above. Note, that particle and particle spawners have differences. + glow = 15, + -- ^ optional, specify particle self-luminescence in darkness. + values may vary from 0 (no glow) to 15 (bright glow). } ### `ParticleSpawner` definition (`add_particlespawner`) @@ -4151,6 +4320,20 @@ The Biome API is still in an experimental phase and subject to change. -- ^ Uses texture (string) playername = "singleplayer" -- ^ Playername is optional, if specified spawns particle only on the player's client + material_type_param = 12641, + -- ^ optional, if specified spawns particle with specified material type + -- param and disable z-buffer. + -- Some examples: + -- Default value: 0, + -- Additive blend: 12641, + -- Substractive blend: 12548, + -- Invert blend: 12597, + -- See also "Particle blend". + animation = {Animation definition}, + -- ^ see above. Note, that particle and particle spawners have differences. + glow = 15, + -- ^ optional, specify particle self-luminescence in darkness. + values may vary from 0 (no glow) to 15 (bright glow). } ### `HTTPRequest` definition (`HTTPApiTable.fetch_async`, `HTTPApiTable.fetch_async`) |