Implement Source Engine material proxy system #51

New issue

Open

opened 2026-03-20 10:10:58 +00:00 by kit · 0 comments

kit commented

2026-03-20 10:10:58 +00:00

Owner

Problem

Source Engine materials use a Proxies {} block in VMT files to drive dynamic material parameters at runtime. We currently hardcode individual proxy behaviors (TextureScroll UV offsets, AnimatedTexture frame cycling) as special cases in the material resolver, which doesn't scale and doesn't correctly handle how proxies interact with shader-specific transform variables.

What's needed

A general-purpose proxy evaluation system that:

Parses the full Proxies {} block from VMTs, supporting multiple proxies per material and preserving proxy type + parameters
Evaluates proxies each frame — each proxy reads input parameters, computes a result, and writes to an output material parameter
Maps proxy outputs to shader uniforms — e.g. $bumptransform → UV transform matrix, $basetexturetransform → base texture UV transform

Common proxy types to implement

TextureScroll — scrolls a texture transform variable over time ($bumptransform, $basetexturetransform)
AnimatedTexture — cycles through VTF frames at a specified rate, targeting any texture variable ($basetexture, $normalmap, $refracttinttexture, etc.)
TextureTransform — computes a texture transform matrix from center/scale/rotate/translate parameters
Sine / LinearRamp / Clamp — mathematical proxies that compute scalar values from time
PlayerProximity / PlayerView — game-state-driven proxies (would need server data)

Current state

$animatedtextureframerate is parsed from VMTs and used for VTF frame cycling on baseTexture and normalMap uniforms
texturescrollvar / texturescrollrate / texturescrollangle are parsed and applied as UV offsets
Both are implemented as flat per-material registrations in MaterialResolver, not as a proxy evaluation system
Refract-specific workaround maps $bumptransform scroll to base texture — this should be handled by the shader's transform variable mapping instead

Architecture

The proxy system should be a separate module that:

Takes a parsed VMT proxy block
Creates proxy instances per material
Provides an update(time) method called each frame
Writes computed values to material uniforms via a parameter mapping layer

#47 — Animated VTF textures (partially implemented, should migrate to proxy system)
#8 — VMT shader types

## Problem Source Engine materials use a `Proxies {}` block in VMT files to drive dynamic material parameters at runtime. We currently hardcode individual proxy behaviors (TextureScroll UV offsets, AnimatedTexture frame cycling) as special cases in the material resolver, which doesn't scale and doesn't correctly handle how proxies interact with shader-specific transform variables. ## What's needed A general-purpose proxy evaluation system that: 1. **Parses the full `Proxies {}` block** from VMTs, supporting multiple proxies per material and preserving proxy type + parameters 2. **Evaluates proxies each frame** — each proxy reads input parameters, computes a result, and writes to an output material parameter 3. **Maps proxy outputs to shader uniforms** — e.g. `$bumptransform` → UV transform matrix, `$basetexturetransform` → base texture UV transform ## Common proxy types to implement - **TextureScroll** — scrolls a texture transform variable over time (`$bumptransform`, `$basetexturetransform`) - **AnimatedTexture** — cycles through VTF frames at a specified rate, targeting any texture variable (`$basetexture`, `$normalmap`, `$refracttinttexture`, etc.) - **TextureTransform** — computes a texture transform matrix from center/scale/rotate/translate parameters - **Sine** / **LinearRamp** / **Clamp** — mathematical proxies that compute scalar values from time - **PlayerProximity** / **PlayerView** — game-state-driven proxies (would need server data) ## Current state - `$animatedtextureframerate` is parsed from VMTs and used for VTF frame cycling on `baseTexture` and `normalMap` uniforms - `texturescrollvar` / `texturescrollrate` / `texturescrollangle` are parsed and applied as UV offsets - Both are implemented as flat per-material registrations in `MaterialResolver`, not as a proxy evaluation system - Refract-specific workaround maps `$bumptransform` scroll to base texture — this should be handled by the shader's transform variable mapping instead ## Architecture The proxy system should be a separate module that: - Takes a parsed VMT proxy block - Creates proxy instances per material - Provides an `update(time)` method called each frame - Writes computed values to material uniforms via a parameter mapping layer ## Related - #47 — Animated VTF textures (partially implemented, should migrate to proxy system) - #8 — VMT shader types