Material

const Material: object

Defined in: client/api.d.ts:914

Per-entity material overrides, the M2O counterpart of MTA’s engineApplyShaderToWorldTexture. A model’s materials are shared by every instance of that asset, so an override gives one entity a private copy and writes through its handle affect only that entity. Nothing is replicated: every client that should see the change must apply it itself.

Type Declaration

count()

count(handle): number

Counts the materials the override covers.

Parameters

handle

number

A handle from override.

Returns

number

The number of instanced materials.

getAimedTextureNames()

getAimedTextureNames(maxDistance?): bigint[]

The texture names of the surface under the crosshair, found with a render-scene line query, so it reaches static world geometry as well as vehicles and peds. Asynchronous: the first call starts the query and returns empty, a later one collects the result, so retry a frame or two apart. Empty also means the ray missed. Feed the result to replaceWorldTextures.

Parameters

maxDistance?

number

How far to cast, in metres; 50 by default.

Returns

bigint[]

getParams()

getParams(handle, index): number[]

Lists the shader parameter ids the material accepts. setParam refuses anything outside this set, because writing an id the shader does not have corrupts the material.

Parameters

handle

number

A handle from override.

index

number

Material index.

Returns

number[]

The parameter ids.

getSamplers()

getSamplers(handle, index): number[]

Lists the texture sampler ids the material’s shader exposes, in template order.

Parameters

handle

number

A handle from override.

index

number

Material index.

Returns

number[]

The sampler ids.

getTexture()

getTexture(handle, index, sampler): bigint

Reads the texture a sampler currently draws.

Parameters

handle

number

A handle from override.

index

number

Material index.

sampler

string | number

A sampler id, or the four characters it packs.

Returns

bigint

The texture name, or 0n when the sampler is unbound or absent.

getWorldTextureNames()

getWorldTextureNames(): bigint[]

Every distinct texture name the currently loaded materials sample, for discovering what a scene draws. Names are hashes, so compare them against Texture.nameOf(path).

Returns

bigint[]

override()

override(entity): number | null

Clones every material the entity’s model draws with. The override is dropped automatically when the entity streams out or respawns.

Parameters

entity

Vehicle | Player

The streamed entity to give private materials to.

Returns

number | null

A handle for the other Material functions, or null when the entity is not streamed or draws nothing overridable.

replaceTexture()

replaceTexture(handle, from, to): number

Rebinds wherever a sampler draws from, so a surface can be targeted without knowing sampler ids.

Parameters

handle

number

A handle from override.

from

bigint

The texture a sampler currently draws.

to

bigint

A Texture.load result, or null to clear.

Returns

number

How many samplers were rebound.

replaceWorldTexture()

replaceWorldTexture(from, to): number

Swaps a texture across every loaded material at once, the M2O counterpart of MTA’s engineApplyShaderToWorldTexture. Unlike override this needs no entity, so it reaches roads, buildings and props; materials are shared, so it is global by design. Returns how many samplers were rewritten.

Parameters

from

bigint

The texture name the world currently draws, from Texture.nameOf or getWorldTextureNames.

to

bigint

A Texture.load result or a render target’s name.

Returns

number

replaceWorldTextures()

replaceWorldTextures(from, to): number

Replaces many texture names in one pass. Prefer this over calling replaceWorldTexture in a loop: each single call walks every loaded material, so a loop over thousands of names costs thousands of walks.

Parameters

from

bigint[]

Texture names to replace.

to

bigint

A Texture.load result or a render target’s name.

Returns

number

restore()

restore(handle): boolean

Puts the original shared materials back and releases the clones.

Parameters

handle

number

A handle from override.

Returns

boolean

True when the override was restored; false when it was already gone.

restoreWorldTexture()

restoreWorldTexture(from): number

Puts one world texture replacement back.

Parameters

from

bigint

The original texture name passed to replaceWorldTexture.

Returns

number

restoreWorldTextures()

restoreWorldTextures(): void

Puts back every world texture replacement made by the calling resource.

Returns

void

setParam()

setParam(handle, param, values, index?): number

Writes a shader parameter. Materials whose shader lacks the parameter are skipped.

Parameters

handle

number

A handle from override.

param

string | number

A parameter id from getParams, or the four characters it packs.

values

number[]

The float payload the parameter expects.

index?

number

One material; omit to write every material the model has.

Returns

number

How many materials were written.

setTexture()

setTexture(handle, sampler, texture, index?): number

Binds a texture to a sampler. Materials whose shader lacks the sampler are skipped.

Parameters

handle

number

A handle from override.

sampler

string | number

A sampler id, or the four characters it packs (“S018” is the vehicle livery sampler).

texture

bigint | null

A Texture.load result, or null to clear the sampler.

index?

number

One material; omit to write every material the model has.

Returns

number

How many materials were written.