Skip to main content

Meta-Parameters Guideline

The meta parameter is a meta-instruction area presented in the form of a CompoundTag. It is designed to ensure compatibility and extensibility for future updates.

You can selectively fill in meta content based on the explanations of the following flags, your requirements, and the current version.

info

Some values provided below offer recommended ranges. While you may fill in values beyond the recommended range in the game, we do not recommend you do so. Filling in values beyond the recommended range is undefined behavior.

Tada​

Available Since：0.3.+

Format："tada":1

Value Type: Boolean (0 or 1)

Indicates that this is a Tada command, and the client needs to calculate the player's hand position and apply an offset when generating particles.

Math Expressions：dx, dy, dz​

Available Since：0.4.+

Format："dx":"<math expression f(t)>"

Example："dy":"0.2*sin(3t)+0.5*t"

Value Type: String

You can provide a function expression with t as the independent variable to gain advanced control over particle increments on the X, Y, and Z axes for each tick. Since directly controlling the particle's absolute coordinates would greatly affect the reusability of the command, assume you want the particle's motion trajectory on the X-axis to be F(t), and you need to provide its derivative f(t) to eliminate the impact of absolute coordinates.

Similarly, to mitigate the impact of different particle lifetimes on command reusability, t ranges from 0 to 1 (corresponding to particle generation to disappearance), and system would scale it according to particle lifetime during actual application.

caution

If you specify dx, dy, dz here:

  • The effects of gravity, xDeflection, and zDeflection will be overridden, and friction will be overwritten.
  • The effect of interactWithEntity (interaction with players) will accumulate.
info

Considering that complex expressions may impact performance, the current calculation method is as follows:

  1. If dx, dy, dz are specified, the initialization of particle objects will be handed over to other threads, with each command corresponding to a thread, initializing a batch of particles.
    1. The initialization process includes the precomputation of dx, dy, dz: 101 values between 0.00 and 1.00 (or particle lifetime + 1 if it's less than 100) are substituted into the given expression for t, and the corresponding values are calculated for querying.
  2. Once a batch of particles is initialized, they will be added to the world at the appropriate time.
  3. When particles are in motion, they read the saved dx, dy, dz arrays and use a similar SIN mode like alphaMode to obtain corresponding values through table lookup and linear interpolation.

The benefit of this approach is to minimize the impact of particles on MSPT, but the current downside is that it will consume relatively more memory resources.

Supported Operators​

The following operators are supported:

  • +, -, *, /: Addition, subtraction (negative), multiplication, division.
  • ^: Power.
  • %: Modulus.

As shown in the example, you can omit the multiplication sign when appropriate.

Supported Constants​

The following constants are supported:

  • pi or π: Pi, 3.14159265358979323846.
  • e: Euler's number, 2.7182818284590452354.
  • φ: Golden ratio, 1.61803398874.

Supported Functions​

The following functions are supported:

  • abs: Absolute value.
  • sin, cos, tan: Sine, cosine, tangent; angles are in radians.
  • asin, acos, atan: Inverse sine, inverse cosine, inverse tangent.
  • sinh, cosh, tanh: Hyperbolic sine, hyperbolic cosine, hyperbolic tangent.
  • sqrt, cbrt: Square root, cube root.
  • floor, ceil: Largest integer not greater than x, smallest integer not less than x.
  • exp: Exponential function with base e.
  • log, log10, log2: Natural logarithm (base e), common logarithm (base 10), logarithm (base 2).
  • signum: Signum function.

Scientific Notation​

Technically supported, but I can't think of any particles that would need scientific notation...

Life Error​

Available Since: 0.4.+

Format: "life":"<error percentage>"

Example: "life":"20"

Value Type: Integer (1 to 99)

Overrides the default 10% lifespan error during particle generation. The example represents a 20% lifespan error.

Disappear on Collision​

Available Since: 0.4.3+

Format: "disappearOnCollision":"<collision count>"

Example: "disappearOnCollision":"2"

Value Type: Integer (greater than 0)

Causes particles to disappear immediately upon reaching the specified collision count. In the example, particles disappear on the second collision.

You can use this feature in combination with expireThen to make a particle transform into another particle upon collision.

Reversed Particle​

info

This is an long-term experimental flag, which means it may be changed or removed in the future.

Available Since: 0.4.7+

Format: "tenet":1

Value Type: Boolean (0 or 1)

Pre-computes particle generation and trajectory, and then adds particles to the world and plays the trajectory in reverse upon generation.

caution

If you specify "tenet":1:

  • interactWithEntity (player interaction) will be disabled.
  • It cannot react to terrain changes that occur after particle precomputation.

Brightness​

info

This is a testing phase flag, which means it has not undergone full testing and may exhibit anomalies in certain cases (e.g., when using shaders).

Available Since: 0.4.9+

Format: "light":"<math expression f(t)>"

Example: "light":"15t"

Value Type: String

Similar to dx, dy, dz, you can provide a function expression with t as the independent variable. It will be applied using precomputation-lookup-interpolation, where the function value will be rounded down during calculation and constrained to the range of 0 to 15.

caution

Reversed Particles flag (i.e., the tenet flag) do not affect Brightness changes.