Module: material

Material API. Contains methods to control parameters of materials.
Source:

Summary

Methods

Type Definitions

Detailed Description

Methods

check_specular_hardness(obj, mat_name) → {boolean}

Check the specular hardness for the object material.
Parameters:
Name Type Description
obj Object3D Object 3D
mat_name string Material name
Returns:
Specular hardness presence
Type
boolean
Deprecated since 17.06:
  • not needed anymore.
Source:
Example
var m_scenes = require("scenes");
var m_mat = require("material");

var cube = m_scenes.get_object_by_name("Cube");
var has_specular_hardness = m_mat.check_specular_hardness(cube, "MyMaterial");

check_specular_intensity(obj, mat_name) → {boolean}

Check the specular intensity for the object material.
Parameters:
Name Type Description
obj Object3D Object 3D
mat_name string Material name
Returns:
Specular intensity presence
Type
boolean
Deprecated since 17.06:
  • not needed anymore.
Source:
Example
var m_scenes = require("scenes");
var m_mat = require("material");

var cube = m_scenes.get_object_by_name("Cube");
var has_specular_intensity = m_mat.check_specular_intensity(cube, "MyMaterial");

get_alpha_factor(obj, mat_name) → {number}

Get the diffuse alpha factor for the object non-node material.
Parameters:
Name Type Description
obj Object3D Object 3D
mat_name string Material name
Returns:
Diffuse alpha factor value
Type
number
Source:
Example
var m_scenes = require("scenes");
var m_mat = require("material");

var cube = m_scenes.get_object_by_name("Cube");
var alpha_factor = m_mat.get_alpha_factor(cube, "MyMaterial");

get_ambient_factor(obj, mat_name) → {number}

Get the ambient factor for the object non-node material.
Parameters:
Name Type Description
obj Object3D Object 3D
mat_name string Material name
Returns:
Ambient factor value
Type
number
Source:
Example
var m_scenes = require("scenes");
var m_mat = require("material");

var cube = m_scenes.get_object_by_name("Cube");
var ambient_factor = m_mat.get_ambient_factor(cube, "MyMaterial");

get_diffuse_color(obj, mat_name) → {RGBA}

Get the diffuse color and alpha for the object non-node material.
Parameters:
Name Type Description
obj Object3D Object 3D
mat_name string Material name
Returns:
Material diffuse color+alpha
Type
RGBA
Source:
Example
var m_scenes = require("scenes");
var m_mat = require("material");

var cube = m_scenes.get_object_by_name("Cube");
var diffuse_color = m_mat.get_diffuse_color(cube, "MyMaterial");

get_diffuse_color_factor(obj, mat_name) → {number}

Get the diffuse color factor for the object non-node material.
Parameters:
Name Type Description
obj Object3D Object 3D
mat_name string Material name
Returns:
Diffuse color factor value
Type
number
Source:
Example
var m_scenes = require("scenes");
var m_mat = require("material");

var cube = m_scenes.get_object_by_name("Cube");
var diffuse_color_factor = m_mat.get_diffuse_color_factor(cube, "MyMaterial");

get_diffuse_intensity(obj, mat_name) → {number}

Get the diffuse color intensity for the object non-node material.
Parameters:
Name Type Description
obj Object3D Object 3D
mat_name string Material name
Returns:
Diffuse intensity value
Type
number
Source:
Example
var m_scenes = require("scenes");
var m_mat = require("material");

var cube = m_scenes.get_object_by_name("Cube");
var diffuse_intensity = m_mat.get_diffuse_intensity(cube, "MyMaterial");

get_emit_factor(obj, mat_name) → {number}

Get the emit factor for the object non-node material.
Parameters:
Name Type Description
obj Object3D Object 3D
mat_name string Material name
Returns:
Emit factor value
Type
number
Source:
Example
var m_scenes = require("scenes");
var m_mat = require("material");

var cube = m_scenes.get_object_by_name("Cube");
var emit_factor = m_mat.get_emit_factor(cube, "MyMaterial");

get_line_params(obj) → (nullable) {LineParams}

Get the parameters of a LINE object.
Parameters:
Name Type Description
obj Object3D Line object 3D
Returns:
Line parameters
Type
LineParams
Source:
Example
var m_scenes = require("scenes");
var m_mat  = require("material");

var line_object = m_scenes.get_object_by_name("MyLine");
var line_params = m_mat.get_line_params(line_object);

get_material_extended_params(obj, mat_name) → (nullable) {MaterialExtParams}

Get the material extended params for the object non-node material.
Parameters:
Name Type Description
obj Object3D Object 3D
mat_name string Material name
Returns:
Material extended params or null
Type
MaterialExtParams
Source:
Example
var m_scenes = require("scenes");
var m_mat = require("material");

var cube = m_scenes.get_object_by_name("Cube");
var extended_parameters = m_mat.get_material_extended_params(cube, "MyMaterial");

get_materials_names(obj) → {Array.<string>}

Get materials' names for the given object.
Parameters:
Name Type Description
obj Object3D Object 3D
Returns:
Array of materials' names
Type
Array.<string>
Source:
Example
var m_scenes = require("scenes");
var m_mat = require("material");

var cube = m_scenes.get_object_by_name("Cube");
var material_list = m_mat.get_materials_names(cube);

get_nodemat_rgb(obj, name_list, destopt) → (nullable) {RGB}

Get color of the RGB node in the object's material.
Parameters:
Name Type Attributes Description
obj Object3D Object 3D
name_list Array.<string> List consisting of the material name, the names of nested node groups (if any) and the name of the RGB node itself. For a world node material the material name should be omitted.
dest Vec3 <optional>
 Destination color
Returns:
Destination color
Type
RGB
Source:
Example
var m_scenes = require("scenes");
var m_mat  = require("material");

var cube = m_scenes.get_object_by_name("Cube");
var rgb_node_values = m_mat.get_nodemat_rgb(cube, ["MyMaterial", "MyRGB"]);

get_nodemat_value(obj, name_list) → {number}

Get value of the Value node in the object's material.
Parameters:
Name Type Description
obj Object3D Object 3D
name_list Array.<string> List consisting of the material name, the names of nested node groups (if any) and the name of the Value node itself. Should have at least 2 elements ["Mat","Node"]. For a world node material the material name should be omitted.
Returns:
Value.
Type
number
Source:
Example
var m_scenes = require("scenes");
var m_mat  = require("material");

var cube = m_scenes.get_object_by_name("Cube");
var node_value = m_mat.get_nodemat_value(cube, ["MyMaterial", "MyValue"]);

get_specular_color(obj, mat_name) → {RGB}

Get the specular color for the object non-node material.
Parameters:
Name Type Description
obj Object3D Object 3D
mat_name string Material name
Returns:
Specular color
Type
RGB
Source:
Example
var m_scenes = require("scenes");
var m_mat = require("material");

var cube = m_scenes.get_object_by_name("Cube");
var specular_color = m_mat.get_specular_color(cube, "MyMaterial");

get_specular_color_factor(obj, mat_name) → {number}

Get the specular color factor for the object non-node material.
Parameters:
Name Type Description
obj Object3D Object 3D
mat_name string Material name
Returns:
Specular color factor
Type
number
Source:
Example
var m_scenes = require("scenes");
var m_mat = require("material");

var cube = m_scenes.get_object_by_name("Cube");
var specular_color_factor = m_mat.get_specular_color_factor(cube, "MyMaterial");

get_specular_hardness(obj, mat_name) → {number}

Get the specular color hardness for the object non-node material.
Parameters:
Name Type Description
obj Object3D Object 3D
mat_name string Material name
Returns:
Specular color hardness
Type
number
Source:
Example
var m_scenes = require("scenes");
var m_mat = require("material");

var cube = m_scenes.get_object_by_name("Cube");
var specular_hardness = m_mat.get_specular_hardness(cube, "MyMaterial");

get_specular_intensity(obj, mat_name) → {number}

Get the specular color intensity for the object non-node material.
Parameters:
Name Type Description
obj Object3D Object 3D
mat_name string Material name
Returns:
Specular color intensity
Type
number
Source:
Example
var m_scenes = require("scenes");
var m_mat = require("material");

var cube = m_scenes.get_object_by_name("Cube");
var specular_intensity = m_mat.get_specular_intensity(cube, "MyMaterial");

get_water_material_params(obj, mat_name) → (nullable) {WaterMaterialParams}

Get the parameters of a water non-node material.
Parameters:
Name Type Description
obj Object3D Object 3D
mat_name string Water material name
Returns:
Water material params or null.
Type
WaterMaterialParams
Source:
Example
var m_scenes = require("scenes");
var m_mat = require("material");

var water = m_scenes.get_object_by_name("MyWater");
var water_params = m_mat.get_water_material_params(water, "MyMaterial");

inherit_material(obj_from, mat_from_name, obj_to, mat_to_name)

Inherit the batch material from another object.
Parameters:
Name Type Description
obj_from Object3D Source Object 3D
mat_from_name string Source material name
obj_to Object3D Destination Object 3D
mat_to_name string Destination material name
Source:
Example
var m_mat = require("material");
var m_scenes = require("scenes");

var cube = m_scenes.get_object_by_name("Cube");
var cube_001 = m_scenes.get_object_by_name("Cube.001");
m_mat.inherit_material(cube, "MyMaterial_1", cube_001, "MyMaterial_2");

is_node_material(obj, mat_name) → {boolean}

Check if the object's material is a node material.
Parameters:
Name Type Description
obj Object3D Object 3D
mat_name string Material name
Returns:
The result of the checking.
Type
boolean
Source:
Example
var m_scenes = require("scenes");
var m_mat = require("material");

var cube = m_scenes.get_object_by_name("Cube");
var has_nodes = m_mat.is_node_material(cube, "MyMaterial");

is_water_material(obj, mat_name) → {boolean}

Check if the object's material is a water material.
Parameters:
Name Type Description
obj Object3D Object 3D
mat_name string Material name
Returns:
The result of the checking.
Type
boolean
Source:
Example
var m_scenes = require("scenes");
var m_mat = require("material");

var cube = m_scenes.get_object_by_name("Cube");
var is_water = m_mat.is_water_material(cube, "MyMaterial");

set_alpha_factor(obj, mat_name, alpha_factor)

Set the alpha factor for the object non-node material.
Parameters:
Name Type Description
obj Object3D Object 3D
mat_name string Material name
alpha_factor number Alpha factor value
Source:
Example
var m_mat = require("material");
var m_scenes = require("scenes");

var cube = m_scenes.get_object_by_name("Cube");
m_mat.set_alpha_factor(cube, "MyMaterial", 0.2);

set_ambient_factor(obj, mat_name, ambient_factor)

Set the ambient factor for the object non-node material.
Parameters:
Name Type Description
obj Object3D Object 3D
mat_name string Material name
ambient_factor number Ambient factor value
Source:
Example
var m_scenes = require("scenes");
var m_mat = require("material");

var cube = m_scenes.get_object_by_name("Cube");
m_mat.set_ambient_factor(cube, "MyMaterial", 0.6);

set_diffuse_color(obj, mat_name, color)

Set the diffuse color and alpha for the object non-node material.
Parameters:
Name Type Description
obj Object3D Object 3D
mat_name string Material name
color RGBA Color+alpha vector
Source:
Example
var m_mat = require("material");
var m_scenes = require("scenes");
var m_rgba = require("rgba");

var cube = m_scenes.get_object_by_name("Cube");
m_mat.set_diffuse_color(cube, "MyMaterial", m_rgba.from_values(1.0, 0.0, 0.0, 1.0));

set_diffuse_color_factor(obj, mat_name, diffuse_color_factor)

Set the diffuse color factor for the object non-node material.
Parameters:
Name Type Description
obj Object3D Object 3D
mat_name string Material name
diffuse_color_factor number Diffuse color factor value
Source:
Example
var m_scenes = require("scenes");
var m_mat = require("material");

var cube = m_scenes.get_object_by_name("Cube");
m_mat.set_diffuse_color_factor(cube, "MyMaterial", 0.05);

set_diffuse_intensity(obj, mat_name, intensity)

Set the diffuse color intensity for the object non-node material.
Parameters:
Name Type Description
obj Object3D Object 3D
mat_name string Material name
intensity number Diffuse intensity value
Source:
Example
var m_scenes = require("scenes");
var m_mat = require("material");

var cube = m_scenes.get_object_by_name("Cube");
m_mat.set_diffuse_intensity(cube, "MyMaterial", 0.5);

set_emit_factor(obj, mat_name, emit_factor)

Set the emit factor for the object non-node material.
Parameters:
Name Type Description
obj Object3D Object 3D
mat_name string Material name
emit_factor number Emit factor value
Source:
Example
var m_mat = require("material");
var m_scenes = require("scenes");

var cube = m_scenes.get_object_by_name("Cube");
m_mat.set_emit_factor(cube, "MyMaterial", 1);

set_line_params(obj, line_params)

Set parameters for a LINE object.
Parameters:
Name Type Description
obj Object3D Line object 3D
line_params LineParams Line parameters
Source:
Example
var m_mat = require("material");
var m_scenes = require("scenes");

var empty = m_scenes.get_object_by_name("Empty");
m_mat.set_line_params(empty, {
    color: [1.0, 0.0, 0.0, 1.0],
    width: 5
});

set_material_extended_params(obj, mat_name, mat_params)

Set the material extended params for the object non-node material.
Parameters:
Name Type Description
obj Object3D Object 3D
mat_name string Material name
mat_params MaterialExtParams Material params
Source:
Example
var m_scenes = require("scenes");
var m_mat = require("material");

var cube = m_scenes.get_object_by_name("Cube");
m_mat.set_material_extended_params(cube, "MyMaterial", {
    fresnel: 0,
    fresnel_factor: 1.25,
    parallax_scale: 0,
    parallax_steps: 5,
    reflect_factor: 0
});

set_nodemat_rgb(obj, name_list, r, g, b)

Set color of the RGB node in the object's material.
Parameters:
Name Type Description
obj Object3D Object 3D
name_list Array.<string> List consisting of the material name, the names of nested node groups (if any) and the name of the RGB node itself. For a world node material the material name should be omitted.
r number The value to set the red channel of the RGB node to [0..1]
g number The value to set the green channel of the RGB node to [0..1]
b number The value to set the blue channel of the RGB node to [0..1]
Source:
Example
var m_mat = require("material");
var m_scenes = require("scenes");

var cube = m_scenes.get_object_by_name("Cube");
m_mat.set_nodemat_rgb(cube, ["MyMaterial", "RGB.001"], 1, 0, 1);

set_nodemat_value(obj, name_list, value)

Set value of the Value node in the object's material.
Parameters:
Name Type Description
obj Object3D Object 3D
name_list Array.<string> List consisting of the material name, the names of nested node groups (if any) and the name of the Value node itself. Should have at least 2 elements ["Mat","Node"]. For a world node material the material name should be omitted.
value number The value to set the Value node to
Source:
Example
var m_mat = require("material");
var m_scenes = require("scenes");

var cube = m_scenes.get_object_by_name("Cube");
m_mat.set_nodemat_value(cube, ["MyMaterial", "Value.001"], 20);

set_specular_color(obj, mat_name, color)

Set the specular color for the object non-node material.
Parameters:
Name Type Description
obj Object3D Object 3D
mat_name string Material name
color RGB Color vector
Source:
Example
var m_mat = require("material");
var m_scenes = require("scenes");

var cube = m_scenes.get_object_by_name("Cube");
m_mat.set_specular_color(cube, "MyMaterial", [0, 0.8, 0]);

set_specular_color_factor(obj, mat_name, factor)

Set the specular color factor for the object non-node material.
Parameters:
Name Type Description
obj Object3D Object 3D
mat_name string Material name
factor number Specular color factor
Source:
Example
var m_scenes = require("scenes");
var m_mat = require("material");

var cube = m_scenes.get_object_by_name("Cube");
m_mat.set_specular_color_factor(cube, "MyMaterial", 0.8);

set_specular_hardness(obj, mat_name, hardness)

Set the specular color hardness for the object non-node material.
Parameters:
Name Type Description
obj Object3D Object 3D
mat_name string Material name
hardness number Specular hardness value
Source:
Example
var m_mat = require("material");
var m_scenes = require("scenes");

var cube = m_scenes.get_object_by_name("Cube");
m_mat.set_specular_hardness(cube, "MyMaterial", 0.8);

set_specular_intensity(obj, mat_name, intensity)

Set the specular color intensity for the object non-node material.
Parameters:
Name Type Description
obj Object3D Object 3D
mat_name string Material name
intensity number Specular intensity value
Source:
Example
var m_mat = require("material");
var m_scenes = require("scenes");

var cube = m_scenes.get_object_by_name("Cube");
m_mat.set_specular_intensity(cube, "MyMaterial", 0.7);

set_water_material_params(obj, mat_name, water_mat_params)

Set parameters for a water non-node material.
Parameters:
Name Type Description
obj Object3D Object 3D
mat_name string Water material name
water_mat_params WaterMaterialParams Water material parameters.
Source:
Example
var m_scenes = require("scenes");
var m_mat = require("material");

var water = m_scenes.get_object_by_name("MyWater");
var water_params = m_mat.set_water_material_params(water, "MyMaterial", {
    waves_height: 2, 
    waves_length: 20, 
    shallow_water_col: [0, 0.3, 0.8]
});

Type Definitions

LineParams

Line params.
Type:
  • Object
Properties:
Name Type Attributes Description
color RGBA <optional>
 Line diffuse color
width number <optional>
 Line width in pixels
Source:

MaterialExtParams

Additional group of parameters for a non-node material.
Type:
  • Object
Properties:
Name Type Attributes Description
fresnel number <optional>
 Power of Fresnel for mirror reflection.
fresnel_factor number <optional>
 Blending factor for Fresnel.
parallax_scale number <optional>
 Scale parameter for texture wrapping. Available if the parallax effect is enabled on the material's normal map texture.
parallax_steps number <optional>
 Number of steps taken to build a parallax surface. Available if the parallax effect is enabled on the material's normal map texture.
reflect_factor number <optional>
 Amount of mirror reflection.
Source:

WaterMaterialParams

Parameters for a water material.
Type:
  • Object
Properties:
Name Type Attributes Description
shore_smoothing boolean <optional>
 Perform the smoothing between the water and the shore objects. Can be used only for Add, Alpha Blend and Alpha Sort materials.
absorb_factor number <optional>
 Water absorb factor. Used only if the "shore_smoothing" parameter is true for this material.
foam_factor number <optional>
 Water foam intensity factor. Can be used if there is a foam texture in this material.
shallow_water_col RGB <optional>
 Color of the shallow water.
shore_water_col RGB <optional>
 Color of the shore water.
shallow_water_col_fac number <optional>
 Shallow water color factor.
shore_water_col_fac number <optional>
 Shore water color factor.
norm_uv_velocity number <optional>
 Water normalmap UV velocity. Can be used if there is a normalmap texture in this material.
water_dynamic boolean <optional>
 Dynamic water surface. If disabled in the blend-file, then this option cannot be enabled via API.
sss_strength number <optional>
 Strength of subsurface scattering. Used if the "water_dynamic" parameter is true.
sss_width number <optional>
 Width of subsurface scattering. Used if the "water_dynamic" parameter is true.
waves_height number <optional>
 Waves height. Used if the "water_dynamic" parameter is true.
waves_length number <optional>
 Waves length. Used if the "water_dynamic" parameter is true.
dst_noise_scale0 number <optional>
 Distant waves noise scale (first component). Used if the "water_dynamic" parameter is true.
dst_noise_scale1 number <optional>
 Distant waves noise scale (second component). Used if the "water_dynamic" parameter is true.
dst_noise_freq0 number <optional>
 Distant waves noise frequency (first component). Used if the "water_dynamic" parameter is true.
dst_noise_freq1 number <optional>
 Distant waves noise frequency (second component). Used if the "water_dynamic" parameter is true.
dir_min_shore_fac number <optional>
 Minimum shore factor for directional waves. Used if the "water_dynamic" parameter is true.
dir_freq number <optional>
 Directional waves frequency. Used if the "water_dynamic" parameter is true.
dir_noise_scale number <optional>
 Directional waves noise scale. Used if the "water_dynamic" parameter is true.
dir_noise_freq number <optional>
 Directional waves noise frequency. Used if the"water_dynamic" parameter is true.
dir_min_noise_fac number <optional>
 Directional waves minimum noise factor. Used if the "water_dynamic" parameter is true.
dst_min_fac number <optional>
 Distant waves min factor. Used if the "water_dynamic" parameter is true.
waves_hor_fac number <optional>
 Strength of horizontal waves inclination. Used if the "water_dynamic" parameter is true.
Source: