Skip to content

tsl.md

Latest commit

 

History

History
98 lines (76 loc) · 3.75 KB

tsl.md

File metadata and controls

98 lines (76 loc) · 3.75 KB
Raw

Trait Shader Language (TSL) Compiler

Compiles HoloScript visual traits directly to WGSL (WebGPU Shader Language) — letting artists describe materials and effects with traits while the GPU executes native shaders.

Overview

The TSL compiler (--target tsl) implements Trait Shader Language: HoloScript's visual trait declarations become compiled WGSL vertex and fragment shaders. It emits WGSL string modules plus a TypeScript pipeline file, not Three.js TSL Fn/node-graph JavaScript. You never write a shader; you write traits.

holoscript compile material.holo --target tsl --output ./shaders/

This is HoloScript's bridge between the declarative spatial layer and the raw GPU pipeline.

Output Structure

shaders/
  [ObjectName].vert.wgsl     # Vertex shader per object
  [ObjectName].frag.wgsl     # Fragment shader per object
  [ObjectName].compute.wgsl  # Compute shader (if needed)
  materials.json             # Bind group layouts

Trait → Shader Mapping

HoloScript Trait Generated Shader Feature
@glowing Fresnel rim + HDR emissive output
@emissive Emissive PBR term in fragment shader
@reflective Specular GGX BRDF
@transparent Alpha blending / OIT
@animated Vertex displacement animation
@particle Compute-based particle system
@gaussian_splat Gaussian splatting splat render
@volumetric Raymarched volume shader
@nerf NeRF sample + accumulate shader
@water FFT ocean surface shader
@holographic Scanline + chromatic aberration
@xray Depth-based transparency
ai_texture_gen Passes UV to Stable Diffusion pipeline

Example

composition "MaterialDemo" {
  object "Crystal" {
    geometry: "sphere"
    @glowing
    @reflective
    @transparent

    color: "#00ffff"
    opacity: 0.75
    emission_intensity: 2.5
  }
}

Compiles to a WGSL fragment shader combining Fresnel rim glow, GGX reflectance, and alpha-blended transparency — without writing a single line of WGSL.

Generated fragment shader (excerpt):

@fragment
fn fs_main(in: VertexOutput) -> @location(0) vec4<f32> {
  // @glowing — Fresnel rim
  let rim = pow(1.0 - abs(dot(in.normal, view_dir)), 3.0);
  // @reflective — GGX specular
  let spec = GGX_brdf(in.normal, view_dir, light_dir, 0.1);
  // @transparent — alpha blend
  let alpha = mix(0.2, 1.0, rim) * uniforms.opacity;
  return vec4(base_color + rim * emission + spec, alpha);
}

Compiler Options

Option Default Description
--tsl-optimize true Run Naga optimizer over generated WGSL
--tsl-compute false Emit separate compute shaders for @particle
--tsl-compat-webgl false Emit GLSL fallback alongside WGSL
--tsl-sourcemap false WGSL source-map back to .holo trait lines

Pipeline Integration

The TSL output is consumed by:

  1. @holoscript/runtime — loads WGSL directly into WebGPU pipeline
  2. WebGPU Compiler — bundles shaders with the WebGPU scene
  3. NIRToWGSL Compiler — uses the same WGSL output format for neuromorphic compute shaders

See Also