pytha.create_material

Creates a new material in the current PYTHA document.

Adds a material entry, sets its name and initial attributes, and returns an element handle that can be passed to set_element_material, set_element_attributes, and get_element_attribute like any other element handle.

Note: Front-side material and per-face material are not supported.

pytha.create_material(name [,options])

Parameter	Type	Description
name	string	Material name. The name has special significance: it is used as the key when materials are saved to .pymat files and shared across documents.
options	{...}	Optional: a table that may contain any of the attribute keys listed below.

Attribute keys (usable in options and in set_element_attributes):

Key	Type	Description
color	{r, g, b}	Base colour in linear sRGB, components in [0, 1].
diffuse	number	Diffuse reflection factor [0, 1].
reflective	number	Specular reflection factor [0, 1].
transparent	number	Transparency factor [0, 1] (0 = opaque).
luminous	number	Self-luminance factor [0, 1].
refractive_index	number	Index of refraction (e.g. 1.5 for glass).
glossiness	number	Gloss sharpness [0, 1] (0 = matte, 1 = mirror).
roughness	number	Surface micro-roughness [0, 1] (physically based; higher values broaden the specular lobe).
texture	path handle	Diffuse texture image (any format PYTHA supports, e.g. PNG, JPG). Takes a path handle, e.g. from pyio.get_plugin_folder_path or pyux.get_library_handle. Raw path strings are not accepted.
bump	path handle	Bump/normal map image. Same rules as texture.
texture_mapping	string	Texture projection mode: "flat" (default), "sphere", "cylinder", or "none".
texture_repeat	{u, v}	Texture repeat distance in mm: {width, height} of one tile.
hidden	boolean	true hides the material in the material library UI.
update_thumbnail	boolean	true regenerates the material thumbnail after applying all other options. Pass this last or as part of the same options table; it is applied after all other keys.

Return value:

Type	Description
element_handle	An element handle of type "material" for the newly created material.

Notes:

• The returned handle is a first-class element handle: get_element_type returns "material", handles can be compared with ==.
• Material names must be unique within the document. If a material with the given name already exists, use find_material to retrieve its handle instead of creating a duplicate.
• This function requires modify access and cannot be called from a read-only context.

Example:

Create a brass material and assign it to a part:

local brass = pytha.create_material("Messing", {
    color            = { 0.83, 0.69, 0.22 },
    diffuse          = 0.6,
    reflective       = 0.7,
    glossiness       = 0.8,
    roughness        = 0.15,
    update_thumbnail = true,
})

local part = pytha.create_block(50, 30, 10)
pytha.set_element_material(part, brass)

Modify an attribute after creation:

pytha.set_element_attributes(brass, { transparent = 0.2, update_thumbnail = true })

Read an attribute back:

local r = pytha.get_element_attribute(brass, "reflective")  -- returns number
local c = pytha.get_element_attribute(brass, "color")       -- returns {r, g, b}

Create a material with a texture shipped in the plugin folder:

local tex = pyio.get_plugin_folder_path("resource/textures/oak.png")
local wood = pytha.create_material("Eiche", {
    texture          = tex,
    texture_mapping  = "flat",
    texture_repeat   = { 600, 600 },
    update_thumbnail = true,
})
pytha.set_element_material(part, wood)

Rename a material:

pytha.set_element_name(brass, "Messing poliert")

Version Support:

Minimum PYTHA Version: V27

See also:

pytha, element handles, path handles, find_material, enumerate_materials, get_element_material, set_element_material, set_element_attributes, get_element_attribute, set_element_name