In a particle simulation, the single thread mode and multi-threading mode refer to how the simulation is processed.

• Single thread mode: In this mode, the simulation is processed sequentially, with all calculations being performed in a single thread of execution. This means that only one calculation is performed at a time and the simulation may be slower, especially for larger simulations.
• Multi-threading mode: In this mode, the simulation is processed in parallel, with calculations being performed simultaneously in multiple threads of execution. This can significantly speed up the simulation, especially for larger simulations, as multiple calculations can be performed at the same time.

With the ExpressionME-L Node the mode of execution is determined by the order of the inputs, with the first input being processed in multi-threading mode and all subsequent inputs being processed in single thread mode. This means you must decide which input should be processed in multi-threading mode based on which input will be most valuable to be processed in parallel.

In addition to the order of inputs, the type of input can determine the mode in which the simulation is processed. For example:

• If the first input is an OpenVDB grid, the expression will go through all grid Voxels in parallel.
• If the first input is a particle group (PGroup), the expression will iterate over all particles in the group in parallel.
• If the first input is a generator, the expression will iterate over all particle IDs generated by the generator in parallel.
• If the first input is an object list, the expression will iterate over all vertices of all objects in the list in parallel (this is the default behavior). You can also specify the mode using a function in the expression.

Other inputs, such as scalars, vectors, or particles, will result in single calls with no parallel iterations.

ME-L groups behave similarly to thinkingParticles' own particle groups, with the exception that they do not have a hierarchy. The same particle can be in several groups. Virtual ME-L groups are accessible throughout multiple ME-L nodes, either in one or many DynamicSets. Accessing virtual ME-L Groups between multiple nodes is done via a strict naming convention. By using the identical name in every ME-L Node, the same group properties will be shared as well.

As with any Node input, when the first input is an ME-L group, the data stored within will be processed in a multi-threaded parallel manner.  

ME-L allows you to programmatically create, rename and move Input and Output connections. You may create various input types like Scalar, Vector etc…

This function allows you to set the name and color of the ME-L node itself.

Call:

exp_desc(in_name, in_exp_param, in_exp_param_value,....);

//set the expression name and color
exp_desc('Hello World', exp_color, 1,1,1);


//example for an Iterative call of the ME-L Node running this script

// IO Block 
   input_desc('iterations',port_scalar,port_r_integer,port_p_min,1);
/IO Block End

exp_desc('My Script', exp_iteration, 'iterations_in'); // the input sets the amount of iterations.

Parameters:

exp_param options:

this function is used to programmatically create an input port for the ME-L node.
Note, Group inputs automatically offer a drop down list of particle groups, including a checkbox for subgroups in the Parameters Rollout section.

Call:

//create a input port
    input_desc(in_name, in_port_type, in_port_param, port_param_value,....)

//create a scalar input port
    input_desc('scalar', port_scalar);

//create a scalar input port and set the min and max and default value
    input_desc('scalar', port_scalar, port_p_min, 0, port_p_max, 10, port_p_default, 5);
    
    //create a vector input port
    input_desc('vector', port_vector);

//create a vector input port with default values
    input_desc('vector', port_vector, port_p_default, 1,1,1);

//create a pgroup input port and set use sub groups
    input_desc('group', port_group, port_p_usesub, true);

//create a scalar input with a dropdown resource this list is zero based (Item1=0)
    input_desc('scalar', port_scalar, port_r_dropdown, 'Item1,Item2,...');

//Example: create a check box
    input_desc('scalar', port_scalar, port_r_checkbox);

//Multi ME-L Node range Groups. Create a virtual ME-L group input which can not be connected, port  name is the group access name!
    input_desc('mgroup_name', port_mgroup);

//add or change the particle color for a virtual ME-L group in the viewport, this will add color swatch resource to the parameter rollout                 R G B  
    input_desc('mgroup_name', port_mgroup, port_p_color, 1,0,0);

//To clear a ME-L group before the expression is called, "pre clear" to start with an empty group
    input_desc('mgroup_name', port_mgroup, port_p_clear, true);

//create a Text Separator in the rollout
input_desc('New Parameter', port_separator);

// Create rollout menue
input_desc('New Parameter', port_separator, port_r_rollout);

Parameters:

This function enables the creation of output ports for the ME-L node. It is essential to understand that since the software supports multi-threading and processes data in parallel, each output port can only hold a single “final” value. Therefore, it is necessary to determine whether the output should be an average, weighted average, minimum or maximum value, using designated flags. These flags will indicate what type of output the software should produce. One output value is created per full evaluation of the ME-L script. 

Example: Lets assume the first input is a particle group with 1000 particles, then the ME-L script is evaluated 1000 times and after this, one value is available at its output port.

Call:

//create a output port
    output_desc(in_name, in_port_type, in_port_param, port_param_value,....)

//create a scalar input port
    output_desc('scalar', port_scalar); // by default, it will output the average value

//scalar output, this outputs the average of all values (can be omitted)
    output_desc('scalar', port_scalar, port_out_average);

//scalar output, sets the minimum value as output
    output_desc('scalar', port_scalar, port_out_min);

//create a scalar output, set the max as output of all values set to the scalar_out
    output_desc('scalar', port_scalar, port_out_max);

//create a vector input port
    output_desc('vector', port_vector);

/create a vector output, make a average of all vector set to the vector_out (that is also the default when no port_out parameter is set)
    output_desc('vector', port_vector, port_out_average);

//create a vector  output, set the min length vector as output of all values set to the vector_out
    output_desc('vector', port_vector, port_out_min);

//create a vector  output, set the max length vector as output of all values set to the vector_out
    output_desc('vector', port_vector, port_out_max);

//create a vector  output, set the min per vector component as output of all values set to the vector_out, vector.x = min x, vector.y = min y, vector.z = min z 
    output_desc('vector', port_vector, port_out_cmin);

//create a vector  output, set the max per vector component as output of all values set to the vector_out, vector.x = max x, vector.y = max y, vector.z = max z 
    output_desc('vector', port_vector, port_out_cmax);

Parameters:

input_desc('pgroup',port_group);\\
output_desc('avgspeed',port_scalar,port_out_average);\\
\\
var mass = get_pdata(pid, data_mass); %%//%%get the mass of the particle\\
\\
avgspeed_out = get_pdata(pid, data_vel) * mass;  %%//%%set the speed weighted with the mass\\
avgspeed_out_avg_weight = mass;  %%//%%weight for the average creation (default is 1, when not set)

In the example above, we collect all particle velocities (with get_pdata). Then, we weight the velocities by the individual particle mass (get_pdata). the scalar_out_avg_weight variable defines the weight factor for the average velocity calculation. Heavier particles have more influence than lighter ones.

Example 2:

// io block start
input_desc('group',port_group);
input_desc('fog',port_vdb_fog);

output_desc('fog',port_vdb_fog,port_p_copyfrom_values,'fog_in'); // this is our copy from
// io block end

var psize=0;
get_pdata(pid,data_size,psize);
fog_out_wraster(1, wp, psize*0.5, 1, set_max, true);

In this example, particle data is used to transfer data into a fog field, before particle evaluation takes place. The current value is copied to the output fog field. Then, the particles are evaluated and the new fog value is set to the max value for each voxel.

This function is used to create a new named memory value, each value is visible throughout all MEL operators. If you use multiple ME-L Nodes in a thinkingParticles setup, the memory slots will be accessible throughout regardless of DynamicSet. Keep in mind; to actually publish the memory slot throughout the ME-L Nodes in tP, press the Compile button.

mem_desc('value1', port_scalar);
mem_desc('value2', port_scalar);
mem_desc('value3', port_scalar);

To store a value in a previously created memory slot you would use the following calls:

mem_set(pid, value1_m, 1); // setting 1 as value    
mem_set(pid, value2_m, 10);// setting 10 as value
mem_set(pid, value3_m, 23);// setting 23 as value    

To read the values form the memory slots you would use the following calls:

var myvalue;
mem_get(pid, value3_m, myvalue); // myvalue will hold now 23

Call:

//make a scalar value
    mem_desc('name', port_scalar);

//create a scalar value with a depth of 1, the default depth is 0, 1 means two values, one value in depth (level) 0 and one in depth 1
    mem_desc('name', port_scalar, port_mem_depth, 1);

//create a scalar value and set the default value to -1, without this parameter the default value is 0
    mem_desc('name', port_scalar, port_p_default, -1);

//create a scalar value and set default value to -1 and min -1 max 10 clamp value
    mem_desc('name', port_scalar, port_p_default, -1, port_p_min, -1, port_p_max, 10);

//create a vector[3] value
    mem_desc('name', port_vector);

//create a vector value with a depth of 1, the default depth is 0, 1 means two values, one value in depth (level) 0 and one in depth 1
    mem_desc('name', port_vector, port_mem_depth, 1);

//create a vector value and set the default to value[0] = -1, value[1] = 0, value[2] = 0, with out this parameter the default values are all 0
    mem_desc('name', port_vector, port_p_default, -1, 0, 0);

//create a vector value and set the default value to -1 and min -1 max 10 clamp value
    mem_desc('name', port_scalar, port_p_default, -1, -1, -1, port_p_min, -1, -1, -1, port_p_max, 10, 10, 10);

Parameters:

This function is used to set a value to a previously created memory slot.    Call:

// set a scalar memory value (in depth 0)
    mem_set(in_pid, name_m, in_scalar);   
    mem_set(in_pid, name_m, in_scalar, 0); // default is 0 anyway so can be omitted

//set a scalar memory value in depth 1
    mem_set(in_pid, name_m, in_scalar, 1);

Parameters:

This function is used to get a value to a previously created memory slot. 

Call:

// set a scalar memory value (in depth 0)
    mem_get(in_pid, name_m, out_scalar);   
    mem_get(in_pid, name_m, out_scalar, 0); // default is 0 anyway so can be omitted

// get a scalar memory value in depth 1
    mem_get(in_pid, name_m, out_scalar, 1);

Parameters:

The ExpressionVDB Node uses a strict order methodology, the first input determines the type of object that the expression will iterate over. If the first input is a group of particles, for example, the expression will execute for each particle in the group in parallel.

noise(x, y, z)
3D Perlin noise function. x, y, and z represent 3D coordinates.

noise(x, y)
2D Perlin noise function. x and y represent 2D coordinates.

ncellular(x, y, z)
3D cellular noise function. x, y, and z represent 3D coordinates.

nchip(x, y, z)
3D cellular noise function in chip mode. x, y, and z represent 3D coordinates.

nvoronoi(x, y, z)
3D Voronoi noise function. x, y, and z represent 3D coordinates.

nturbulence(position_in, size_in, shift_in, frequency_in, turb_out)
This function computes a 3D vector turbulence field based on the specified parameters. The inputs include the position_in, size_in, shift_in, and frequency_in, each contributing to the generation of turbulence. The resulting turbulence vector is stored in the turb_out variable. By leveraging this function, users can introduce controlled perturbations into their simulations, effectively simulating turbulent behaviors within three-dimensional space. The function serves as a valuable tool for achieving realistic and dynamic effects in visual simulations by providing a flexible means to manipulate the turbulence characteristics.

Parameters:

rndseed(s) 
Sets the random seed.

rnd01()
Returns a random value between 0.0 and 1.0.

rnd11()
Returns a random value between -1.0 and 1.0.

rndxx(x, y)
Returns a random value between x and y.

prnd01()
Per particle random function that returns a repeatable series of random values between 0.0 and 1.0.

prnd11() 
Per particle random function that returns a repeatable series of random values between -1.0 and 1.0.

prndxx()
Per particle random function that returns a repeatable series of random values between a specified range.

nrndseed(in_generator_id, in_seed)
Initializes the random generator with a specified seed. The input generator id can be 0 or 1, with 0 being the standard generator and 1 being a more regular generator. The input seed is a random seed value. Returns 0 on failure and 1 on success.

nrnd01(in_generator_id) 
Returns a random value between 0.0 and 1.0 using the specified generator id (0 or 1).

pnrnd01(in_generator_id)
Per particle variant of the nrnd01 function, returns a repeatable series of random values between 0.0 and 1.0 using the specified generator id (0 or 1).

nrnd11(in_generator_id)
Returns a random value between -1.0 and 1.0 using the specified generator id (0 or 1).

pnrnd11(in_generator_id)
Per particle variant of the nrnd11 function, returns a repeatable series of random values between -1.0 and 1.0 using the specified generator id (0 or 1).

nrndxx(in_generator_id, in_from_value, in_to_value)
Returns a random value between a specified range (in_from_value and in_to_value) using the specified generator id (0 or 1).

pnrndxx(in_generator_id,in_from_value,in_to_value) 
Per particle variant of the nrndxx function, returns a repeatable series of random values between a specified range (in_from_value and in_to_value) using the specified generator id (0 or 1).

Prints information or data to the standard thinkingParticles Debug window. The window must be open for the function to work.

Call:

dprint(string,string/vector/scalar, ... up to 8 values);

dprint(color{3}, string,string/vector/scalar, ... up to 8 values); %%//%% RGB color of text

dprint(color{3}); // sets the RGB color of text for the next print commands

dprint(scalar); // boolean 1: turns dprint on (default), 0: turns dprint off

dprint(scalar,color[3]); // boolean 1: turns dprint on (default), 0: turns dprint off. And RGB color!

Formatting options:

Return: 1: when the function was successful, 0: when the function did not print out something (e.g debug window closed)

Example:
Print debug information

dprint('hello world'); // prints out Hello World

dprint('Size: ',7); // prints out "Size: 7"

dprint('World Position: ', wp, 'Time: ', t); // prints out "World Position: v[0}= 1 v[1}= 4 v[2}= -2 Time: 1.2"

var red[3] = {1,0,0}; // RGB

dprint(red,'This text is in RED'); // this prints out in red color: "This text is in RED"

dprint('Position$w', pos[3]); // shows the position value in world scale units e.g [ 2.54mm # 22mm # 78mm ]

dprint('$c',color[3]); // shows the value as RGB e.g [ 0.54R # 0.22G # 0.78B ]

The dmarker function introduces a dynamic marker into the 3ds Max viewport, allowing users to enhance visualization with selectable color, shape and customizable lifespan (stayframes).
This function empowers users to dynamically visualize specific points in the 3ds Max viewport, adding a layer of clarity and precision to the overall visualization process.

Call:

 dmarker(type_in, worldposition_in, color_in or intensity_in, stayframes_in)

Parameters

Marker Type (style)

Example:

// create a ticks marker in yellow
var color[3]= {1,1,0};// Yellow
var pos[3]= {0,0,50}; //Place 50 above ground

dmarker(0, pos, color, 30); // Keep the marker visible for 30 frames

// Place a marker at an exact particle position (using global variable wp)
dmarker(0, wp, color, 0); // Keep the marker visible for one frame

This function introduces a streamlined approach to draw lines in the 3ds Max viewport, offering flexibility in type, color, and duration.

Call:

 
 dline(type_in, color_in or intensity_in, stayframe_in, worldposion_in, nextworldposion_in, ...)
 

Parameters

Line Types

Example:

 
// create a line from origin to Z-Up position
var pos_o[3]={0,0,0}; // origin
var pos_up[3]={0,0,50}; // Z-up end point
var color[3]={0,0,1}; // blue color

dline(0, color, 0, pos_o, pos_up); // draw the line form 0,0,0 to 0,0,50
 
 

This function empowers users to display text dynamically in the 3ds Max viewport, offering versatile options for color, size, and content.

Call:

 
 dtext(type_in, worldposition_in, color_in, textsize_in, stayframes_in, string scalar or string_in, ...) 
 

Parameters:

 
// draw the scalar length value formatted to world units, 
// internally, 3ds Max is always using generic units
var pos[3];
var col[3];
var len;
	
dtext(0, pos, col, 2, 0, 'Length$w', len)
  

lowhighcut(v, low, high)
Converts the range between low and high to a range between 0.0 and 1.0.

ndistance(vector pos1, vector pos2, norm_radius)
Returns the distance between pos1 and pos2, normalized by dividing by norm_radius.

distance(vector pos1, vector pos2)
Returns the distance between pos1 and pos2.

dir_length(invector, outdirection)
Calculates the length of the input vector and stores the resulting direction in outdirection. This returns a normalized vector with a length of 1. This factually represents a normalize vector function.

sqrdistance(vector pos1, vectorpos2)
Returns the squared distance between pos1 and pos2.

• pos1[1] is 1D
• pos1[2] is 2D
• pos1[3] is 3D

length_(vector_in)
calculates the length of a given vector (vector_in).  √(x*x+y*y+z*z)

sqr_length_(vector_in)
calculates the length of a vector as a  square of its length. (x*x+y*y+z*z)

angle_axis_rotate(in_angle, in_axis[3], in_out_vector[3]) Rotates a vector around a specified axis by a specified angle (in radian (use deg2rad() to specify in degrees). The input vector is modified and returned.

angle_axis_rotate(in_angle, in_axis[3], in_vector[3], out_vector[3]) Rotates a vector around a specified axis by a specified angle (use deg2rad() to specify in degrees). The input vector is not modified and the rotated vector is returned.

dir_variation(in_angle, in_out_vector[3]) Randomly varies a vector by a specified angle (use deg2rad() to specify in degrees). The input vector is modified and returned.

dir_variation(in_angle, in_vector[3], out_vector[3]) Randomly varies a vector by a specified angle (use deg2rad() to specify in degrees). The input vector is not modified and the varied vector is returned.

dir_variation(in_angle1, in_angle1, in_out_vector[3]) Randomly varies a vector between 2 angles (min and max) by a specified amount (use deg2rad() to specify in degrees). The input vector is modified and returned.

dir_variation(in_angle1, in_angle2, in_vector[3], out_vector[3]) Randomly varies a vector between 2 angles by a specified amount (use deg2rad() to specify in degrees). The input vector is not modified and the varied vector is returned.

pos_variation(in_distance, in_out_vector[3]) Randomly varies a position by a specified distance. The input vector is modified and returned.

pos_variation(in_distance, in_vector[3], out_vector[3]) Randomly varies a vector by a specified distance. The input vector is not modified and the varied vector is returned.

crossprod(in_vector1[3], in_vector2[3], out_vector[3]) Calculates the cross product between 2 vectors. The Result is returned in the out_vector. Basic vector math function :)

Return: The functions returns 0 on failure and 1 on success.`

slerp(in_t_scalar, in_to_vector[3], in_out_from_vector[3])
slerp(in_t_scalar, in_to_vector[3], in_from_vector[3], out_vector[3])
These two functions facilitate Spherical Linear Interpolation, where rotation occurs from the “from vector” to the “to vector” with a transition weight “t,” where “t” ranges between 0 and 1. A value of 1 signifies the utilization of 100% of the “to vector.”
The second variation of this function not only performs the Spherical Linear Interpolation but also writes the interpolated vector (result) into a separate variable, enhancing flexibility and control in your scripting endeavors. These additions to the ME-L scripting language expand the toolkit for 3D artists, providing precise control over rotations and enabling the creation of dynamic and sophisticated visual effects.

cgradient (min_in, vlaue_in, max_in, color_in, …., color_out)
Interpolates a color between two values from a list of colors. This function takes parameters including min_in (scalar minimum value), value_in (scalar value), max_in (scalar maximum value), color_in (a comma-separated list of vector[3] colors), and outputs the interpolated color in color_out. The resulting color is determined based on the scalar value relative to the specified minimum and maximum values, creating a smooth color transition within the defined color range.

Parameters:

rate(in_rate_per_second)
Returns a constant rate, used for generating particles at a specified rate per second. The internal time and delta time are used.

rate(in_rate_per_secund, in_time, in_delta_time)
Returns a constant rate, used for generating particles at a specified rate per second. The input time and delta time are used instead of the internal values.

Parameters:

Return: The function returns the rate between time - delta_time and time. The sum of all rates in one second should equal the specified rate per second (in_rate_per_secound).

Example:
To create 50 particles per second, the following code can be used:

var born;

if(born = rate(50))
{
  for(var i = 0; i < born; i+=1)
  {
   group_in_create(pos, vel);
  }
}

retrieves data for a specific particle id. The data can either be returned as a direct return value or supplied variable in the call itself.

Call Example:

get_pdata(pid, data_type, ret_value, optional dt) // return via ret_value

return = get_pdata(pid, data_type) %%//%% Direct Return Mode

// use transformation calls
// transform world to particle
get_pdata(pid, data_ptransform, world2object, in_point[3], out_point[3]);
get_pdata(pid, data_ptransform, world2object, in_out_point[3]); // return to the same variable

//transform a vector without scale and translation, only the rotation is being computed
//the vector keeps its length, there is a direction change, only
get_pdata(pid_in, data_dtransform, object2world, vector_in_out); 
get_pdata(pid_in, data_dtransform, object2world, vector_in, vector_out); 

//special transformation for normals, no translation is being computed
//a normal is orthogonal to a face therefore a special transformation to keep its direction, is needed
get_pdata(pid_in, data_ntransform, object2world, vector_in_out); 
get_pdata(pid_in, data_ntransform, object2world, vector_in, vector_out); 

//transform a point without scale but with translation and rotation
//the vector keeps its length, there is a direction change, only
get_pdata(pid_in, data_trtransform, object2world, vector_in_out); 
get_pdata(pid_in, data_trtransform, object2world, vector_in, vector_out); 

This function takes the following parameters:

Return -
The function returns a scalar value, with 0 indicating no access to the particle (in which case the ret_value will not be set) and 1 indicating success (in which case the ret_value will be set to the data).
When this function is called in a direct return mode (return is assigned to a variable) the actual value will be stored/returned.

// get the mass of particle with pid 10
var mass = 1;
get_pdata(10, data_mass, mass);

// get the color data channel 1 of the local iterate particle
var color[3];
get_pdata(pid, data_dchan+1, color);

// get the speed of the particle
var speed = 0;%%//%%no vector only a scalar the function evaluate the velocity vector length for a scalar return value\\
get_pdata(pid, data_vel, speed);

// get the velocity of the particle
var velocity[3];
get_pdata(pid, data_vel, velocity);

// Direct Mode method
// get the velocity of the particle
var speed;
speed=get_pdata(pid, data_vel);


if(get_pdata(pid,data_genter))
{
  // Do something when particle enters the group
}

used to set standard particle data for a specific particle id

Call Example: <coce> set_pdata(pid, data_type, value) </code>      

Return: 
(Scalar) 0 indicates no access to the particle (ret_value will be not valid), 1 indicates success and ret_value is set to the requested data

Examples:

// Set the velocity of the particle with pid 10 to 0 
vel = [0, 0, 0] set_pdata(10, 'data_vel', vel) 

// Set the color red into the data channel 1 of the local iterate particle color = [1, 0, 0] set_pdata(pid, 'data_dchan+1', color)

This function is used to align the specified axis of a particle with a given position, direction, or rotation.

Call Example:

// align the particle x axis to world position
set_palignment(pid_in, x_axis_, align_topos, position_in, optional laziness_in)

//align the particle y axis to world position
set_palignment(pid_in, y_axis_, align_topos, position_in, optional laziness_in)

//align the particle z axis to world  position
set_palignment(pid_in, z_axis_, align_topos, position_in, optional laziness_in)    

//align the particle x axis to world direction    
set_palignment(pid_in, x_axis_, align_dir, direction_in, optional laziness_in)

//align the particle y axis to world direction
set_palignment(pid_in, y_axis_, align_dir, direction_in, optional laziness_in)

//align the particle z axis to world direction
set_palignment(pid_in, z_axis_, align_dir, direction_in, optional  laziness_in)

//align the particle x axis to travel direction (velocity direction)
set_palignment(pid_in, x_axis_, align_travel, optional laziness_in)

// align the particle y axis to travel direction 
set_palignment(pid_in, y_axis_, align_travel, optional laziness_in)

//align the particle z axis to travel direction
set_palignment(pid_in, z_axis_, align_travel, optional laziness_in)

// rotate around the x axis amount of rotation in radians use deg2rad() to use degrees 
set_palignment(pid_in, x_axis_, align_rotate, radians_in)

// rotate around the y axis amount of rotation in radians
set_palignment(pid_in, y_axis_, align_rotate, radians_in)

// rotate around the z axis amount of rotation in radians
set_palignment(pid_in, z_axis_, align_rotate, radians_in)

// rotate around a user axis amount of rotation in radians
set_palignment(pid_in, user_axis_, user_axis_in, align_rotate, radians_in)

//copy the alignment from the in_from_pid particle
    set_palignment(in_pid, from_pid_axis_, in_from_pid);

To access and work with mesh based functions, the function get_pdata must be first called to check if a particle has a mesh attached to it or not. To initiate this check do the following:

get_pdata(in_pid, data_shape)

When this function returns a value of 1 the probed particle (in_pid) holds mesh data.

Used to get a point on the surface of the mesh.

Calls:

pshape_surface_point(in_surface_relative) \\
pshape_surface_point(in_surface_relative, in_mtl_id)

Parameters:

Output:

Get the closest point on the pshape surface to the specified position in world space.

Calls:

pshape_closest_point(pos)
pshape_closest_point(pos, mtl_id)

Output:

This function is used to get surface point data.
Note point data can only be accessed after the function surface_point or closest_point return with a value of 1.

Calls:

pshape_point(point_data, out_scalar)\\
pshape_point(point_data, out_vector[3])\\
pshape_point(point_uvw, in_chan, out_uvw_vector[3])

Parameters:

Output:

Code Example: 

// Get 10 random points on the mesh of the current particle

var pos[3];

if(get_pdata(pid, data_shape))
{
  for(var i = 0; i < 10; i +=1)
  {
   if(pshape_surface_point(rnd01()))
   {
     pshape_point(point_pos, pos);
               
         ...do anything with the position, e.g. create a new particle\\
   };
  }
};

The pshape_geom function allows you to access geometry specific data of a mesh. There are several variations of this function, depending on the type of data you want to retrieve and the format of the output. Check out the possible function calls shown below. Alos note, new functionalities allow users to manage vertex colors more effectively, aligning with 3ds Max conventions. Additionally, a method has been incorporated to access vertex colors in a manner consistent with 3ds Max, addressing the specific way colors are stored in Vertex Color Channels. Explore the expanded capabilities of pshape_geom to refine your control over mesh-specific data retrieval.

Calls:

pshape_geom(geom_data, out_scalar)

pshape_geom(geom_data, out_vector)

pshape_geom(face_data, in_face_id, out_scalar)
pshape_geom(face_data, in_face_id, out_vector)    
pshape_geom(vert_data, in_vertex_id, out_vector) 

// get one of the three face vertex positions
// vert have the range 0-2    
pshape_geom(face_vpos, face_id, vert, vertex_pos_out)

// get the interpolated position on a face
// bc are the barycentric oordinates of the position on the face
pshape_geom(face_pos, face_id, bc, pos[3]_out)

//get the interpolated normal on a face
//bc are the barycentric oordinates of the position on the face
pshape_geom(face_norm, face_id, bc, norm[3]_out)
    
// query face selection state returns 0 if not selected 1 if selected.
return = pshape_geom(face_selected, face_id)

pshape_geom(tface_data, in_map_channnel,in_tface_id, out_scalar)

pshape_geom(tface_data, in_map_channnel, in_tface_id, out_vector)
pshape_geom(tface_data, in_map_channnel, in_tface_id, in_barycentric, out_vector)
pshape_geom(tface_uvw, in_map_channnel, in_tface_id, in_barycentric, out_uvw)

pshape_geom(tvert_data, in_map_channel, in_tvertex_id, out_uvw)

pshape_geom(edge_data, edge_id, scalar_out)
pshape_geom(edge_data, edge_id, vector_out)

//this is the velocity of the particle
pshape_geom(geom_vel, out_velocity[3]);        
    
//this is the velocity on the world position including spin (rotation) of the particle
pshape_in_geom(geom_vel, in_world_position[3], out_velocity[3]); 


//get the two edge face index
//the index range is 0 >= id < nfaces, value of -1 mean undefined
pshape_geom(edge_fid, edge_id, vector[2]_out)

//get the two edge vertex index
//the index range is 0 >= id < nverts
pshape_geom(edge_vid, edge_id, vector[2]_out)

//is edge selected, returns 0 if not selected 1 if selected.
return = pshape_geom(edge_selected, edge_id) 
    
//is edge visible, returns 0 if not visible 1 if visible.
return = pshape_geom(edge_visible, edge_id) 
  
//is edge open, returns 0 if not open1 if open.
return = pshape_geom(edge_open, edge_id) 

//the supplied material id, defines the open edge status (a change of mat id = open)
//mtl_id, range 1 - max material id of 3ds Max.
return = pshape_geom(edge_open, edge_id, mtl_id) 

//get an interpolated position on the edge
//rel_pos, range between 0 - 1
pshape_geom(edge_pos, edge_id, rel_pos, pos[3]_out)


//get an interpolated normal on the edge
//rel_pos, range between 0 - 1
pshape_geom(edge_norm, edge_id, rel_pos, norm[3]_out

// copy particle alignment from this particle to another particle
pshape_geom(geom_palign,in_to_pid); 

// get the number of edges which share the vertex with the id "vid" 
pshape_geom(vert_nedges, vid); 

//get the real edge id from the vertex
pshape_geom(vert_edge, vid, i); 

// get the number of faces sharing the vertex with the id "vid" 
pshape_geom(vert_nfaces, vid); 

//get the real face id from the vertex
pshape_geom(vert_face, vid, i); 

//to get the face vertex color
pshape_geom(face_vcol, in_fid, in_vid, out_color[3])

//interpolated vertex color on the face
pshape_geom(face_vcol_bz, in_fid, in_bc[3], out_color[3])

//get the vertex color of the vertex, this represents the average across all faces connected to this vertex
pshape_geom(vert_vcol, in_vid, color_out[3])

// get the vertex color of the vertex, get from all the faces the vertex color connected 
// to the vertex  and returns the average
pshape_geom(vert_vcol, in_vid, color_out[3])

// you can use any vertex color channel by specifying it as an argument
// 3ds Max supports channles 0-99, thinkingParticles uses channel 0 for original object coordinates (3D-UVW Texture).
pshape_geom(vert_vcol, in_vid, map_channel_in, color_out[3])

Function Call for Geom Data Type:

Function Call for Face Data

Function Call for Texture Face Data

Function Call for Vertex Data

Function Call for Texture Vertex Data

Function Call for Edge Data

Output:

Example:
This code example shows how to get all face centers of a mesh.

    var nfaces;
    var center[3];
        
        if(get_pdata(pid, data_shape))
        {
            if(pshape_geom(geom_nfaces, nfaces))
            {
                for(var i = 0; i < nfaces; i += 1)
                {
                    pshape_geom(face_center, i, center);                  
                  ...do anything\\
                }
            };    
        };

This function sets particle shape mesh data. It can be used to access and interact with face centers, material ID, vertex positions, and vertex indices of a face, as well as the position, color, and UVW coordinates of a vertex.

Calls:

// Geom Initialize Vertex Color

     // initializes the vertex color for a a specified vertex color channel (UVW Channel 0-99). Default 0.
     pshape_geom_set(geom_init_vcol, uvw_channel_in,  fcol_in[3]);
     pshape_geom_set(geom_init_vcol, uvw_channel_in); // uses color 0,0,0 (Black)
     pshape_geom_set(geom_init_vcol ); // uses uvw channel 0 and color 0,0,0 (Black)
     pshape_geom_set(geom_init_vcol, fcol_in[3]); // uses uvw channel 0 

//face data

    //set the world space center of a face, this automatically changes the 3 vertex positions
    pshape_geom_set(face_center, face_id_in, center[3]_in)
    pshape_geom_set(face_ocenter, face_id_in, center[3]_in) //the same in object space
    
    //set the face material id
    pshape_geom_set(face_mtlid, face_id, mtilid_in)
  
    //set one of the three vertex position from the face, vid_in = 0,1,2
    pshape_geom_set(face_vpos, face_id_in, vid_in, position[3]_in)
    pshape_geom_set(face_ovpos, face_id_in, vid_in, position[3]_in) //in object space     

    //set the three vertex index's from the face
    pshape_geom_set(face_vid, face_id_in, vid[3]_in)

//vertex data
    
    //set the world space position of a vertex
    pshape_geom_set(vert_pos  , vert_id_in, position[3]_in)
    pshape_geom_set(vert_opos, vert_id_in, position[3]_in) //the same in object space
    
    //set the vertex color
    pshape_geom_set(vert_col  , vert_id_in, color[3]_in)     

//texture face data

    //set one of the three texture vertex uvw from the texture face, vid_in = 0,1,2
    pshape_geom_set(tface_vpos, face_id_in, vid_in, uvw[3]_in)
    
    //set the three vertex index's from the texture face
    pshape_geom_set(tface_vid, face_id_in, vid[3]_in)

//texture vertex data
    
    //set the texture vertex uvw, chan_id is the mapping channel id 0 - 99
    pshape_geom_set(tvert_uvw, tvert_id_in, chan_id_in, uvw[3]_in)


//Set Individual Vertex Colors

	//set each of the three vertex colors of a face
	pshape_geom_set(face_vcol, in_fid, in_vid, in_color[3])

        //extrapolate vertex color on the face
	pshape_geom_set(face_vcol_bc, in_fid, in_bc[3], in_color[3])

        //set the vertex channel color(selected by vertex ID; in_vid), all connected faces to this vertex will receive the 
        interpolated color.
	pshape_geom(vert_vcol, in_vid, in_color[3])

Function for Geom Data Types

Function Call for Face Data

face_data Types:

Function Call for Texture Face Data

tface_data Types

Function Call for Vertex Data

vert_data Types:

tvert_data Types:

Output:

Get a point on the pshape edges at the specified relative position along the edge's length between 0-1

Calls:

pshape_closest_point(pos)
pshape_closest_point(pos, mtl_id)

Output:

Here we describe workinh with particle references. Please note, this section is just for “readability and ease of use” as there are functions are no special functions to handle references. They are the same get_padata and set_pdatafunctions as described before.

Retrieves reference data from a particle

Calls:

get_pdata(in_pid, data_type, out_value)
get_pdata(in_pid, data_type, in_ref_id, out_value)

Parameters:

data_type values:

Output:

Sets reference data for a particle

Calls:

set_pdata(in_pid, data_type, in_pid_to_set)
set_pdata(in_pid, data_type, usage_type, in_ref_id)

Parameters:

data_type values:

usage_type values:

Output:

Example 1:

 // create 20 particles and set references to them

var ppos1[3];
var pvel1[3];
        for(var i = 0; i < 20; i += 1)
        {
            pid1 = group2_create(ppos1, ppvel1);
            if(pid1 >= 0)
            {
                // set a reference from the current pid to the new particle pid1
                set_pdata(pid, data_ref_from, pid1); // or set_pdata(pid, data_ref_from, usage_set, pid1);
            };
        };

Example 2:

// Go through all "FROM" references

var nrefs;
var pid1;

get_pdata(pid, data_nrefs_from, nrefs);
       for(var i = 0; i < nrefs; i += 1)
        {
            if(get_pdata(pid, data_ref_from, i, pid1))
            {
                ..... do anything with pid1 the to particle    
                        
            }
        } 

The following functions are used to store within one scalar a flag field with a maximum of 32-Bit. Flags are memory efficient methods to control program flow.

Example: You can use one scalar to switch between multiple conditions based on a simple ON/OFF list of flags 

var myflags; //all flags are 0 

flags_set(myflags,0); // set flag 0 to 1. flags_set always sets to 1
flags_set(myflags,3); // set flag 3 to 1. flags_set always sets to 1
flags_set(myflags,0,3); // alternativle we can write this to set 2 or more flags in one go
flags_set(myflags); // set all 32 flags to 1

if(flags_test(myflags,0) > 0); // is flag 0 set to 1?
if(flags_test(myflags,0,3) > 0); // is flag 0 and flag 3 set to 1? Up to 32 flags in one call
if(flags_test(myflags,0)> 0 & flags_test(myflags,3)==0); // is flag 0 set to 1 and flag 3 set to 0?
if(flags_test(myflags) > 0); %%//%% is any flag set to 1?

flags_clear(myflags,0); // set flag 0 to 0
flags_clear(myflags,3); // set flag 3 to 0
flags_clear(myflags,0,3); // set flag 3 and 0 to 0. Up to 32 flags in one call
flags_clear(myflags); // set all flags to 0

Checks if a Flag is set to 1.

Calls:

flags_set(scalar);
flags_set(scalar,flag, ...)

Parameters:

Output:

Checks if a Flag is set to 1.

Calls:

flags_test(scalar); 
flags_test(****scalar,flag, ...)

Parameters:

Output:

Sets a Flag to 0.

Calls:

flags_clear(scalar); 
flags_clear(scalar,flag, ...)

Parameters:

Output:

Used exclusively by:

get_pdata
set_pdata

Used exclusively by: 

group_in_find

used by: 

• group_in_isect_data
• objects_in_point
• pshape_in_point

used by the following function: memory_in_info()

used by the following functions:

• field_out_iset
• field_out_wset
• field_out_iraster
• field_out_wraster
• field_out_iextrapolate
• field_out_wextrapolate

Used by:

• field_in_transform
• field_out_transform
• objects_in_transform

Used by:

• field_in_transform
• field_out_transform
• objects_in_transform
• get_pdata

used exclusively by: 

objects_in_parallel

used by: 

used by:

• scalar_out
• vector_out

used by: lights_in_illum_result 

used by:

lights_in_info

used by:

• splinepool_in_set
• splinepool_in_get

used in:

• splinepool_in_spline
• splinepool_in_set
• splinepool_in_branch
• splinepool_in_get