weapon-materials.md

Weapon material format

Russian translation | Authoring guide | Server API

When drawing a Studio model, the client selects a material by texture name. Outside an edit session, it checks the entity's server binding first, then the model's .mat document. If neither source supplies a material, the client uses the built-in material based on the texture flags. An active edit session temporarily overrides the selected material for its target. Materials require r_studio_shader 1 and r_studio_materials 1.

Model document

Materials for models/v_glock18.mdl are defined in models/v_glock18.mat. The materials section lists model texture names and their assigned materials. Texture names are case-insensitive. A material affects every model part using that texture; the selected skin can change which textures are used.

{
    "version": 1,
    "materials": {
        "glock_slide.bmp": {
            "program": "weapon_finish",
            "params": {
                "uWearMap": { "texture": "materials/masks/wear/blotches.png" },
                "uUnderlay": { "texture": "materials/surfaces/brass.png" },
                "uWear": 0.5
            }
        }
    }
}

A material specifies a required program and an optional params object. Parameter names match the program manifest exactly, including case. A number is a scalar, an array of four numbers is a vector, and {"texture": "path"} is an image reference. The client checks parameter types and ranges against the manifest. Scalars and every vector component must be finite and within declared bounds. Omitted parameters receive declared defaults.

File and image limits

Resource	Limit
Document version	1
Texture entries per model document	64
Parameters per material	64
Distinct image files referenced by a document	64
Image path in a model document	128 bytes
Image path in a server preset	96 bytes
Image formats	PNG or TGA
Image area	1,048,576 pixels

Image paths are relative to the game directory. Use forward slashes and the .png or .tga extension. Absolute paths, drive prefixes, backslashes, control characters, and empty, . or .. segments are rejected. Image area is width * height. Shipped images count toward the file limit. Repeated references to one file count once.

Program manifest

A manifest describes the program’s available parameters: names, types, defaults, allowed ranges, and editor controls. Its main fields are version, program, and parameters. A scalar parameter with instance: true can be changed per entity through the server API. Values are floating-point numbers clamped to the specified range. They are not rounded to a slider step.

The optional render_contract field selects a supported material profile. It must be a nonempty string of at most 64 bytes and is available in manifest version 1. Without this field, the program uses generic parameters.

The built-in studio and weapon_finish programs support the studio_effects_v1 material profile. Its effect parameters must use the supported types, ranges, and defaults. Use the effects reference for the visible behavior and the shipped manifest for exact parameter definitions.

The schema allows 64 parameters and eight texture parameters. Optional groups determine editor sections. Optional strings names the localization file. The shipped weapon_finish manifest contains the authoritative defaults, bounds, and editor grouping.

A scalar with widget: "choice" declares choices as an array of localized labels. Values are integer indices: min is 0, and max is one less than the number of choices, and an integer default in that range. The editor displays a non-editable list. Fractional indices are rejected before clamping; out-of-range integer writes clamp to the range. For example, uOutlineMode uses index 0 for occluded-only outline, 1 for the entire silhouette, and 2 for visible-only outline.

weapon_finish inputs

Parameter	Meaning
uBaseTint	Base-skin color multiplier.
uPattern, uPatternTint, uPatternTransform	Pattern image, tint, and UV placement. Pattern alpha also controls mixing.
uLayerMix	Pattern fraction, 0..1.
uWearMap, uWearMapTransform	Threshold map and UV placement. Dark regions wear first.
uWear	Wear amount, 0..1.
uWearSoftness	Half-width of the transition around the wear threshold.
uUnderlay, uUnderlayTint, uUnderlayTransform	Exposed surface image, tint, and UV placement.
uReflectMask, uReflectMaskTransform	Reflection-strength multiplier and UV placement.
uReflectTint	Color multiplier for the scene-light highlight and matcap reflection.
uReflectWear	Highlight dependence on wear, from -1 (coating) to 1 (exposed areas), with 0 using the mask alone.
uSphereMap, uReflectivity	Image of a lit sphere (matcap) and reflection intensity.
uSpecular, uGloss	Scene-light highlight intensity and exponent.

A UV transform, [scale_u, scale_v, offset_u, offset_v], sets image scale and offset on the surface. The pattern overlays the base texture. Worn areas reveal the underlying layer. The reflection mask controls shine, and scene lighting affects highlights and matcap reflection.

Use matgen to validate a document before delivery. The renderer architecture explains the responsibilities of materials and rendering.

Material effects