Skip to content
github-actions[bot] edited this page Aug 29, 2026 · 3 revisions

Proper Shaders — Modding API

Proper Shaders exposes a C API so other mods (.asi / .dll) can work with its renderer. It currently covers two things:

  • Lights — point and spot lights you create, move, recolour and remove at runtime, with per-light control over how they interact with volumetric fog and volumetric light beams.
  • State queries — what Proper Shaders is doing right now: which features the user has on, which pass is rendering, and the render targets themselves.

The API is resolved at runtime with GetProcAddress. Nothing is linked, so a mod using it still loads and runs normally on a machine where Proper Shaders is not installed — the effects simply do not appear.

Current API version: 2


Start here

Copy ProperShadersAPI.h into your project. It is a single self-contained header with no dependencies beyond the Windows headers, and it works from both C and C++. That is the whole integration — there is nothing to link.

#include "ProperShadersAPI.h"

PS_Api ps;
if (PS_ApiLoad(&ps)) {
    PS_LightDesc d;
    PS_LightDescInit(&d);
    d.position[0] = x; d.position[1] = y; d.position[2] = z;
    d.radius = 12.0f;
    d.intensity = 2.0f;
    d.fogMode = PS_FOGMODE_NORMAL;

    PS_LightHandle light = ps.LightCreate(&d);
}

→ Getting Started for the details, or Example Project for a complete mod you can build and run.


Pages

Getting Started Loading the API, and behaving well when Proper Shaders is absent.
Example Project A complete Plugin-SDK mod using the API.
Lights Creating lights, and every field of PS_LightDesc.
Light Function Reference Every light entry point.
Light Examples Worked examples for common cases.
Budgets and Limits How many lights you get, and what happens past that.
State Queries Enabled features, current render pass, render targets.
Requirements and Fallbacks What the user must have enabled for each effect.
Versioning and Compatibility The two version numbers, and the ABI promise.
Troubleshooting When something does not show up.

Clone this wiki locally