HaulVision Shader Studio

Standalone ATS 1.61.1.1 shader inspection, dumping, faithful HLSL reconstruction, interface validation, and live replacement testing. This guide is completely offline and ships with the clean source/release package.

1. Installation

American Truck Simulator\bin\win_x64\
└─ plugins\
   ├─ HaulVisionShaderStudio.dll
   └─ HaulVisionShaderStudio\
      ├─ data\
      │  ├─ effect_shader_runtime_catalog.csv
      │  ├─ effect_pass_runtime_catalog.csv
      │  ├─ effect_catalog_metadata.json
      │  └─ dxbc_cache\
      ├─ captures\
      └─ logs\

2. Building from source

Double-click BUILD_HAULVISION_SHADER_STUDIO_1_61_1_1.bat. Visual Studio 2022 with Desktop development with C++ is required. Python 3 is optional for normal builds because this clean package already includes the 1.61.1.1 catalogs and DXBC cache.

3. Using Shader Studio in game

Actual in-game standalone Shader Studio UI. The final clean build retains this HaulVision purple/graphite theme and responsive stage filters.

4. Dumping and creating a shader workspace

Select a live shader, then use Create / Refresh Workspace. Shader Studio resolves the exact original DXBC from live memory when possible, otherwise from the verified 1.61.1.1 catalog cache.

Every workspace is organized by stage → effect → full shader identity:

captures\PS\eut2.sky\
└─ PS_391AD521_0FF00CFEF8FD1EA0_eut2.sky\
   ├─ PS_391AD521_0FF00CFEF8FD1EA0_eut2.sky_original.dxbc
   ├─ PS_391AD521_0FF00CFEF8FD1EA0_eut2.sky_faithful.hlsl
   ├─ PS_391AD521_0FF00CFEF8FD1EA0_eut2.sky_replacement.dxbc
   ├─ PS_391AD521_0FF00CFEF8FD1EA0_eut2.sky_live.dxbc
   ├─ PS_391AD521_0FF00CFEF8FD1EA0_eut2.sky_live.asm
   ├─ PS_391AD521_0FF00CFEF8FD1EA0_eut2.sky_faithful_compile.log
   ├─ PS_391AD521_0FF00CFEF8FD1EA0_eut2.sky_faithful_validation.txt
   └─ PS_391AD521_0FF00CFEF8FD1EA0_eut2.sky_shader_info.txt

5. Editing faithful.hlsl

The faithful file is reconstructed from the real DXBC and compiled back using the original shader profile (ps_5_0 or vs_5_0). The safest workflow is to change shader math while preserving the original interface contract.

6. Shader validation — how to get clean replacements

Compile + Load Faithful HLSL does not blindly inject whatever compiled. Shader Studio first compiles the HLSL, then reflects/disassembles the rebuilt DXBC and compares its game-facing interface with the original ATS shader.

The result you want

MISMATCH_CLASS=NONE
RESULT=COMPATIBLE
The rebuilt shader is replacement-ready only when RESULT=COMPATIBLE.

When the validation report ends with RESULT=COMPATIBLE, Shader Studio copies the accepted build to the identity-named _replacement.dxbc and the UI can load it.

If the shader compiles but validation fails

MISMATCH_CLASS=GENERAL_INTERFACE_MISMATCH
RESULT=REJECTED

Do not force-load that shader. Shader Studio moves rejected compiled output to an identity-named _live_REJECTED.dxbc. Open the matching _faithful_validation.txt and find the first MISMATCH line.

Automatic repair categories

Shader Studio can recognize narrowly defined cases such as sparse signature masks, semantic register/lane layout changes, or an original resource-declaration superset. It may attempt an exact interface-skeleton repair. If the report still ends in RESULT=REJECTED, treat it as rejected.

Standard Shader Studio b13 extensions

When Shader Studio creates any shader workspace it also creates captures\_shared\HVSS_StandardBuffers.hlsli. Add one profile define before including that file:

#define HVSS_USE_PARAMS_8_V1 1
#include "HVSS_StandardBuffers.hlsli"

// 8 neutral float4 registers are now declared at b13.
// Give each lane a meaning that makes sense for your replacement.
float exposure = HVSS_PARAM1(0, 0);
float contrast = HVSS_PARAM1(0, 1);
float4 userColor = HVSS_PARAM4(1);

Custom standard size without editing Shader Studio source

If 64/128/192/256 bytes do not fit your project, choose any size from 16 through 256 bytes in 16-byte increments. Define the number of float4 registers, then include the same standard header:

#define HVSS_USE_CUSTOM_PARAMS_V1 1
#define HVSS_CUSTOM_PARAMS_FLOAT4_COUNT 6
#include "HVSS_StandardBuffers.hlsli"

// 6 × 16 bytes = a 96-byte maximum b13 layout.
float strength = HVSS_PARAM1(0, 0);
float radius   = HVSS_PARAM1(0, 1);
float4 tint    = HVSS_PARAM4(1);

Valid custom counts are 1..16. Shader Studio parses the count from the HLSL and records it in the validation report and the generated *.atsvt.ini sidecar. A count of 6, for example, authorizes up to 96 bytes.

How to design a clean custom parameter layout

1. Confirm b13 is free in the original shader. Search the untouched faithful HLSL/assembly and validation resource list. If ATS already owns b13 for that shader, do not add an HVSS b13 extension.
2. Choose the smallest profile that fits. Four scalar/vector registers often cover tint, strength, ranges, and toggles. Do not choose 256 bytes just because it is available.
3. Keep each logical parameter stable. Document what each lane means, for example hvss_param[0].x = exposure and hvss_param[1].xyz = tint. Treat that mapping as your ABI.
4. Use one extension only. Do not combine multiple HVSS_USE_* profiles. Each standard profile targets the same generic b13 extension slot.
5. Do not exceed the declared count. With HVSS_USE_PARAMS_4_V1, valid indexes are 0–3. With a custom count of 6, valid indexes are 0–5.
6. Preserve the ATS interface. The extra b13 block is the only authorized addition. Inputs, outputs, original cbuffers, textures, samplers and slots still have to validate exactly.
7. Read the report after every compile. A clean generic extension reports HVSS_STANDARD_EXTENSION=..., HVSS_STANDARD_SLOT=13, its float4 count/max bytes, then ends with RESULT=COMPATIBLE.

A successful 8-register preset will contain lines similar to:

HVSS_STANDARD_EXTENSION=HVSS_PARAMS_8_V1
HVSS_STANDARD_SLOT=13
HVSS_STANDARD_FLOAT4_COUNT=8
HVSS_STANDARD_MAX_BYTES=128
authorized_resource_additions=1
MISMATCH_CLASS=NONE
RESULT=COMPATIBLE

D3DCompile may reflect a smaller cbuffer if your HLSL only reads the first few registers. Shader Studio therefore accepts a standard extension up to the selected profile's maximum size rather than requiring unused tail registers to survive compilation.

Creating a named standard preset for a distributed project

Most users should use HVSS_USE_CUSTOM_PARAMS_V1; it avoids C++ changes. If you maintain a project and want a stable named preset such as HVSS_USE_MYPROJECT_V1, use the following pattern:

1. Add the named profile to graphics\hvss_standard_buffers_source.hpp and map it to a fixed HVSS_PARAM_FLOAT4_COUNT.
2. Add a matching entry to kStandardExtensions in graphics\dxbc_faithful_decompiler.cpp with the define name, public layout name, and float4 count.
3. Keep the slot at b13 unless you also intentionally redesign the validator/runtime contract. The stock standard validator only authorizes the generic extra cbuffer at b13.
4. Bump the preset version when its byte layout changes. Never silently redefine an existing _V1 layout.
5. Document every lane and provide a runtime that binds the same byte size/slot if the shader expects live values.
6. Compile one edited shader and confirm the report shows the expected profile and RESULT=COMPATIBLE before distributing it.

7. Loading and testing a replacement

1. Select the shader in Live Shaders.
2. Create/refresh its workspace once.
3. Edit the identity-named _faithful.hlsl.
4. Click Compile + Load Faithful HLSL.
5. Only a successfully validated build is accepted by this path.
6. Use Replacement enabled to A/B test edited vs native rendering.
7. Use Restore Original ATS Shader to unload the replacement completely.

8. Troubleshooting

9. Clean package contents

This clean source intentionally excludes old ReShade/ATS Visual Toolkit artifacts, 1.60 target tables, historical phase notes, legacy replacement packs, unused database/decompiled placeholders, obsolete build scripts, and generated Python cache files.

HaulVision_ShaderStudio_STANDALONE_ATS_1.61.1.1_STANDARD_EXTENSIONS\
├─ BUILD_HAULVISION_SHADER_STUDIO_1_61_1_1.bat
├─ HaulVisionShaderStudio.sln
├─ HaulVision_Shader_Studio_Offline_Guide.html
├─ README.md
├─ LICENSE
├─ build\
├─ src\HaulVisionShaderStudio\
├─ tools\
└─ data\
   ├─ current 1.61 catalog files
   └─ dxbc_cache\