aether-engine 1.0.0

package/src/renderer/LitMaterial.ts

@@ -0,0 +1,337 @@
+import { Material } from "./Material";
+
+export const LIT_SPRITE_VS = `
+  attribute vec4 aVertexPosition;
+  attribute vec2 aTextureCoord;
+  attribute vec3 aVertexNormal;
+
+  uniform mat4 uModelMatrix;
+  uniform mat4 uModelViewMatrix;
+  uniform mat4 uProjectionMatrix;
+  uniform vec2 uTexOffset;
+  uniform vec2 uTexScale;
+  
+  varying highp vec2 vTextureCoord;
+  varying highp vec3 vWorldPos;
+  varying highp vec3 vNormal;
+
+  void main(void) {
+    gl_Position = uProjectionMatrix * uModelViewMatrix * aVertexPosition;
+    vTextureCoord = (aTextureCoord * uTexScale) + uTexOffset;
+    
+    // Compute world position for lighting calculations
+    vWorldPos = (uModelMatrix * aVertexPosition).xyz;
+    
+    // Approximate normal transformation using ModelMatrix directly
+    // This is valid for Translation/Rotation uniform scaling
+    vNormal = normalize(mat3(uModelMatrix) * aVertexNormal);
+  }
+`;
+
+export const LIT_SPRITE_FS = `
+  precision mediump float;
+  
+  varying highp vec2 vTextureCoord;
+  varying highp vec3 vWorldPos;
+  varying highp vec3 vNormal;
+  
+  uniform sampler2D uSampler;
+  uniform lowp vec4 uColor;
+
+  // Lighting Uniforms
+  uniform lowp vec3 uAmbientColor;
+  uniform int uActivePointLights;
+  uniform highp vec3 uLightPositions[16];
+  uniform lowp vec3 uLightColors[16];
+  uniform highp vec4 uLightParams[16]; // x: intensity, y: radius, z: physicalElevation, w: flickerIntensity
+
+  // Occlusion map for shadows and screen properties
+  uniform sampler2D uOcclusionSampler;
+  uniform highp vec2 uResolution;
+  uniform highp mat4 uViewMatrix;
+  uniform highp mat4 uProjectionMatrix;
+
+  // Particle Shading System
+  uniform int uActiveParticleLights;
+  uniform highp vec4 uParticleLightPositions[64];
+  uniform lowp vec3 uParticleLightColors[64];
+
+  // Global Time for dynamic effects
+  uniform highp float uTime;
+
+  // Interleaved Gradient Noise for Dithering
+  float IGN(highp vec2 fragCoord) {
+      vec3 magic = vec3(0.06711056, 0.00583715, 52.9829189);
+      return fract(magic.z * fract(dot(fragCoord, magic.xy)));
+  }
+
+  // Tuneable random delay/decay pattern for natural gas flickering
+  float getFlicker(float time, vec3 pos) {
+      // Offset time radically per-lightsource based on prime-scaled coordinates
+      float localTimeOffset = pos.x * 137.0 + pos.y * 311.0;
+      float absoluteTime = time + localTimeOffset;
+      
+      // Determine a distinct 10-second interval block for this exact lamppost
+      float decasecond = floor(absoluteTime * 0.1);
+      
+      // Dice roll strictly once per block independently!
+      float dice = fract(sin(decasecond * 12.9898 + pos.x * 78.233) * 43758.5453);
+      
+      // 1% chance to stutter (e.g. extremely seldom, averages 1 flutter every 16 minutes per lamp)
+      if (dice < 0.015) {
+          float localProgress = fract(absoluteTime * 0.1) * 10.0;
+          
+          if (localProgress < 1.0) {
+              // Chaotic 1-second flutter fading out naturally
+              float noise = fract(sin(time * 50.0 + pos.y) * 43758.5453);
+              float envelope = 1.0 - localProgress; 
+              return 1.0 - (noise * 0.7 * envelope);
+          }
+      }
+      
+      return 1.0;
+  }
+
+  void main(void) {
+    vec4 texColor = texture2D(uSampler, vTextureCoord);
+    if (texColor.a < 0.05) discard;
+    
+    vec4 baseColor = texColor * uColor;
+    
+    vec3 lightAdded = vec3(0.0);
+    vec3 specularAdded = vec3(0.0);
+    vec2 fragUV = gl_FragCoord.xy / uResolution;
+    
+    // Unequivocal structural detection of 2D (Orthographic) vs 3D (Perspective) camera matrices natively.
+    // uProjectionMatrix[3][3] equals 1.0 purely for Orthographic, and 0.0 for Perspective.
+    float is2D = uProjectionMatrix[3][3] > 0.5 ? 1.0 : 0.0;
+    
+    vec3 norm = normalize(vNormal);
+    // Fallback for 2D sprites without normal mappings: Bypass diffuse angle scaling safely
+    if (is2D > 0.5) {
+        norm = vec3(0.0, 0.0, 1.0);
+    }
+    
+    // View direction for Specular (approximate isometric camera angle roughly 45 deg down)
+    vec3 viewDir = normalize(vec3(0.0, 0.707, 0.707));
+
+    // A. CORE POINT LIGHTS (Heavy 12-pass Raymarching shadows)
+    for (int i = 0; i < 16; i++) {
+        if (i >= uActivePointLights) break;
+        
+        vec3 lightPos = uLightPositions[i];
+        vec3 lightColor = uLightColors[i];
+        float intensity = uLightParams[i].x; 
+        float radius = uLightParams[i].y;
+        float height = uLightParams[i].z;
+        float flickerIntensity = uLightParams[i].w;
+        
+        // Authentic pseudo-3D coordinate reconstruction for robust volumetric 2.5D lighting!
+        vec3 physPos = vWorldPos;
+        
+        if (is2D > 0.5) {
+            // Check if this is a standing sprite inherently sorted on Z, or a background/ground tile (-5.0)
+            if (vWorldPos.z > -4.0) {
+                // Standing Sprite! Reconstruct its true 2.5D physical footprint Anchor Y geographically from the internal Z-buffer formula.
+                float trueBaseY = -vWorldPos.z * 100.0;
+                
+                // The geometric Altitude & Elevation of the exact pixel on the sheet!
+                float pixelElevation = max(0.0, vWorldPos.y - trueBaseY);
+                
+                // We construct a TRUE geometric volumetric point using Footprint Y as topological distance, and pixel Altitude as Elevation Z!
+                physPos = vec3(vWorldPos.x, trueBaseY, pixelElevation);
+            } else {
+                // Flat Ground Tile (Z = -5.0). True geological Elevation is strictly 0.0 ground plane.
+                physPos = vec3(vWorldPos.x, vWorldPos.y, 0.0);
+            }
+        }
+        
+        vec3 diff3D = lightPos - physPos; // true physical direction un-normalized
+        float distSq = dot(diff3D, diff3D);
+        float radiusSq = radius * radius;
+        
+        if (distSq < radiusSq) {
+            // Prevent NaN glitches where geometric center aligns flawlessly with a pixel
+            float dist = max(0.001, sqrt(distSq));
+            vec3 lightDir = diff3D / dist;
+            float normDist = dist / radius;
+            
+            // --- Spotlight Cone Directionality ---
+            // A real lamppost has a cap and physically points DOWN and outward natively. 
+            // lightDir.z tracks downward angle perfectly natively in our 2.5D projection!
+            // If pixel is directly below (lightDir.z is large positive), weight is 1.0.
+            // If pixel is horizontal canopy (lightDir.z ~ 0.0), weight smoothly fades to 0.0.
+            float spotlightCone = smoothstep(0.05, 0.4, lightDir.z);
+            
+            // --- Reflectance & Specular ---
+            float diffuse = dot(norm, lightDir) * 0.5 + 0.5;
+            vec3 specular = vec3(0.0);
+            
+            if (is2D > 0.5) {
+                // Disable pure mathematical 3D specular for flat 2D billboard sprites.
+                // This prevents intense radioactive blowouts when isometric angles perfectly align with height offsets.
+                if (vWorldPos.z < -4.0) {
+                     // Tile Ground Plane (Z=-5 internal rendering depth). Inject pseudo-texture bump mapping.
+                     float bump = fract(sin(dot(floor(vWorldPos.xy * 16.0), vec2(12.9898, 78.233))) * 43758.5453);
+                     diffuse = mix(0.9, 0.7 + bump * 0.4, clamp(1.0 - normDist, 0.0, 1.0));
+                } else {
+                     // 100% stable standing 2D Sprite. Use static Half-Lambert facing up to receive
+                     // soft volume lighting that fades uniformly along the edges of the light cone!
+                     diffuse = 0.6 + (dot(vec3(0,0,1), lightDir) * 0.4);
+                }
+            } else {
+                // Authentic 3D Mesh rendering (e.g. Dungeon walls). Execute true structural Specular
+                vec3 halfVector = normalize(lightDir + viewDir);
+                float spec = pow(max(dot(norm, halfVector), 0.0), 16.0); // Shininess = 16.0
+                specular = spec * lightColor * intensity * 0.8;
+            }
+            
+            // Gaussian soft falloff for natural glowing
+            float attenuation = max(0.0, (exp(-normDist * normDist * 4.0) - 0.0183) / 0.9817);
+
+            // Incorporate Downward Cone (Spotlight Cutoff) for 2D sprites.
+            // In pure 3D scenes (like Dungeon), we might want spherical lights. We dynamically apply cone
+            // ONLY if is2D > 0.5 because the cone is essential to prevent horizontal Canopy bleeding in 2D overlays!
+            if (is2D > 0.5) {
+                // If lightDir.z = 1.0 (looking straight down), weight is 1.0.
+                // If lightDir.z < 0.6 (looking primarily horizontally across the scene at tall geometries), weight drops permanently to 0.0!
+                float spotlightCone = smoothstep(0.55, 0.85, lightDir.z);
+                attenuation *= spotlightCone;
+            }
+
+            // Natural, tuneable delay/decay flicker pattern mixed per-light
+            float flickerAmount = getFlicker(uTime, lightPos);
+            attenuation *= mix(1.0, flickerAmount, flickerIntensity);
+            
+            float shadowMultiplier = 1.0;
+            
+            // Disable screen-space raymarch shadows for Point Lights in heavily 2D Isometric modes.
+            // Screen-space Z-depth occlusion inherently destroys 2.5D lighting mathematics 
+            // by forcing upright billboard sprites to cast infinite absolute black shadows linearly across the ground plane.
+            if (is2D < 0.5) {
+                // RAYMARCH SHADOWS:
+                vec4 lClip = uProjectionMatrix * uViewMatrix * vec4(lightPos, 1.0);
+                vec2 lightScreenUV = (lClip.xy / lClip.w) * 0.5 + 0.5;
+                
+                vec2 rayVec = lightScreenUV - fragUV;
+                float stepsNum = 12.0;
+                vec2 stepUV = rayVec / stepsNum;
+                
+                vec2 sampleUV = fragUV;
+                sampleUV += stepUV * (IGN(gl_FragCoord.xy) - 0.5);
+                
+                for (int k = 0; k < 12; k++) {
+                    sampleUV += stepUV;
+                    if (sampleUV.x < 0.0 || sampleUV.x > 1.0 || sampleUV.y < 0.0 || sampleUV.y > 1.0) {
+                        break;
+                    }
+                    vec4 occData = texture2D(uOcclusionSampler, sampleUV);
+                    float isOccluder = 1.0 - occData.b; 
+                    
+                    if (isOccluder > 0.5) {
+                        float normZ = occData.r + occData.g * (1.0/255.0);
+                        float occluderZ = normZ * 20.0 - 10.0;
+                        // For 3D geometry ONLY, cast dynamic shadows downward
+                        if (occluderZ > vWorldPos.z + 0.005) {
+                            shadowMultiplier = 0.0;
+                            break;
+                        }
+                    }
+                }
+            }
+            
+            // Accumulate
+            lightAdded += lightColor * intensity * attenuation * diffuse * shadowMultiplier;
+            specularAdded += specular * attenuation * shadowMultiplier;
+        }
+    }
+    
+    // B. SECONDARY PARTICLE LIGHTS (Fast Path - No shadows, specific radius)
+    vec3 particleAdded = vec3(0.0);
+    
+    for (int j = 0; j < 64; j++) {
+        if (j >= uActiveParticleLights) break;
+        
+        vec3 pLightPos = uParticleLightPositions[j].xyz;
+        float pRadius = uParticleLightPositions[j].w;
+        vec3 pLightColor = uParticleLightColors[j]; // Already scaled by intensity
+        
+        vec3 posToLight = vWorldPos;
+        if (is2D > 0.5) {
+            // Terraria-style pixelated attenuation
+            // Assuming 1 unit = 1 tile = 16 pixels. Quantize position logically to grid.
+            posToLight = floor(vWorldPos * 16.0) / 16.0;
+        }
+
+        vec3 pDiff3D = pLightPos - posToLight;
+        if (is2D > 0.5) {
+            // Particles assume a slight consistent height over the 2D plane
+            pDiff3D.z = 0.5;
+        }
+        
+        float pDistSq = dot(pDiff3D, pDiff3D);
+        float pRadiusSq = pRadius * pRadius;
+        
+        if (pDistSq < pRadiusSq) {
+            float pDist = sqrt(pDistSq);
+            vec3 pLightDir = pDiff3D / pDist;
+            
+            // Half-Lambert
+            float pDiffuse = dot(norm, pLightDir) * 0.5 + 0.5;
+            if (is2D > 0.5) pDiffuse = 1.0;
+            
+            // Gaussian soft falloff
+            float pNormDist = pDist / pRadius;
+            float pAtten = max(0.0, (exp(-pNormDist * pNormDist * 4.0) - 0.0183) / 0.9817);
+            
+            // pure consistent particle light radius logic, particles don't independently sputter
+            
+            if (is2D > 0.5) {
+                // Harsh visual steps
+                pAtten = floor(pAtten * 6.0) / 6.0;
+            }
+            
+            particleAdded += pLightColor * pAtten * pDiffuse;
+            
+            // Slight specular for particles too! 
+            vec3 pHalfVector = normalize(pLightDir + viewDir);
+            float pSpec = pow(max(dot(norm, pHalfVector), 0.0), 32.0); // very shiny points
+            specularAdded += pSpec * pLightColor * pAtten * 0.4;
+        }
+    }
+    
+    // 1. Multiply Blend for ambient context (shadows)
+    vec3 shadedBase = baseColor.rgb * uAmbientColor;
+    
+    // 2. Diffuse mapped light
+    vec3 mappedLight = baseColor.rgb * lightAdded;
+    
+    // 3. To rescue extremely dark flat ground textures from absorbing illumination invisibly, 
+    // we softly inject pure light geometrically. We STRICTLY MUST ONLY do this for Ground Tiles 
+    // (Z < -4) rather than structural sprites like Trees, because Trees possess real color matrices 
+    // that detonate into neon radioactive glitches when synthetic inverse-glow is stacked!
+    vec3 ambientGlow = vec3(0.0);
+    if (is2D > 0.5 && vWorldPos.z < -4.0) {
+        vec3 safeGlowEnergy = min(lightAdded, vec3(1.1));
+        ambientGlow = safeGlowEnergy * (vec3(1.0) - baseColor.rgb) * 0.9; 
+    }
+    
+    vec3 litColor = shadedBase + mappedLight + (baseColor.rgb * particleAdded) + specularAdded + ambientGlow + (particleAdded * 0.1);
+    
+    // No global curve tone mapping. The engine runs naturally unbounded and cleanly handles standard overflow.
+    litColor = clamp(litColor, 0.0, 1.0);
+    
+    // Screen-space Dithering to completely eliminate 8-bit color banding
+    float dither = IGN(gl_FragCoord.xy) * (1.0 / 255.0);
+    litColor += dither - (0.5 / 255.0);
+    
+    gl_FragColor = vec4(litColor, baseColor.a);
+  }
+`;
+
+export class LitMaterial extends Material {
+	constructor() {
+		super(LIT_SPRITE_VS, LIT_SPRITE_FS);
+	}
+}
+

package/src/renderer/Material.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, test } from "bun:test";
+import { Color } from "../math/Color";
+import { Material } from "./Material";
+
+describe("Material System", () => {
+	test("Program hashing", () => {
+		const mat1 = new Material("VS", "FS");
+		const mat2 = new Material("VS", "FS");
+		const mat3 = new Material("VS2", "FS");
+
+		expect(mat1.programHash).toBe(mat2.programHash);
+		expect(mat1.programHash).not.toBe(mat3.programHash);
+	});
+
+	test("Uniforms storage", () => {
+		const mat = new Material("VS", "FS");
+		mat.setUniform("uColor", new Color(255, 0, 0));
+		mat.setUniform("uIntensity", 1.5);
+
+		expect(mat.uniforms.uColor).toBeInstanceOf(Color);
+		expect(mat.uniforms.uIntensity).toBe(1.5);
+	});
+});

package/src/renderer/Material.ts

@@ -0,0 +1,80 @@
+import type { TextureAsset } from "../core/AssetManager";
+import type { Color } from "../math/Color";
+
+export const DEFAULT_MESH_VS = `
+  attribute vec4 aVertexPosition;
+  attribute vec4 aVertexColor;
+  uniform mat4 uModelViewMatrix;
+  uniform mat4 uProjectionMatrix;
+  varying lowp vec4 vColor;
+  void main(void) {
+    gl_Position = uProjectionMatrix * uModelViewMatrix * aVertexPosition;
+    vColor = aVertexColor;
+  }
+`;
+
+export const DEFAULT_MESH_FS = `
+  varying lowp vec4 vColor;
+  void main(void) {
+    gl_FragColor = vColor;
+  }
+`;
+
+export const DEFAULT_SPRITE_VS = `
+  attribute vec4 aVertexPosition;
+  attribute vec2 aTextureCoord;
+  uniform mat4 uModelViewMatrix;
+  uniform mat4 uProjectionMatrix;
+  uniform vec2 uTexOffset;
+  uniform vec2 uTexScale;
+  varying highp vec2 vTextureCoord;
+  void main(void) {
+    gl_Position = uProjectionMatrix * uModelViewMatrix * aVertexPosition;
+    vTextureCoord = (aTextureCoord * uTexScale) + uTexOffset;
+  }
+`;
+
+export const DEFAULT_SPRITE_FS = `
+  precision mediump float;
+  varying highp vec2 vTextureCoord;
+  uniform sampler2D uSampler;
+  uniform lowp vec4 uColor;
+  void main(void) {
+    vec4 texColor = texture2D(uSampler, vTextureCoord);
+    if (texColor.a < 0.05) discard;
+    gl_FragColor = texColor * uColor;
+  }
+`;
+
+export type UniformValue =
+	| number
+	| number[]
+	| Float32Array
+	| Int32Array
+	| Color
+	| TextureAsset
+	| any;
+
+export class Material {
+	public vertexShader: string;
+	public fragmentShader: string;
+	public uniforms: Record<string, UniformValue> = {};
+	public transparent: boolean = false;
+	public depthTest: boolean = true;
+	public depthWrite: boolean = true;
+	public cullFace: boolean = true;
+	public blendMode: "Alpha" | "Additive" | "Screen" = "Alpha";
+
+	public get programHash(): string {
+		return `${this.vertexShader}|${this.fragmentShader}`;
+	}
+
+	constructor(vs: string, fs: string) {
+		this.vertexShader = vs;
+		this.fragmentShader = fs;
+	}
+
+	setUniform(name: string, value: UniformValue) {
+		this.uniforms[name] = value;
+	}
+}

package/src/renderer/OcclusionMaterial.ts

@@ -0,0 +1,43 @@
+import { Material } from "./Material";
+import { LIT_SPRITE_VS } from "./LitMaterial";
+
+export const OCCLUSION_FS = `
+  precision mediump float;
+  
+  varying highp vec2 vTextureCoord;
+  varying highp vec3 vWorldPos; // Must match vertex shader exactly
+  
+  uniform sampler2D uSampler;
+  uniform lowp vec4 uColor;
+  uniform highp vec2 uTexOffset;
+  uniform highp vec2 uTexScale;
+
+  void main(void) {
+    vec4 texColor = texture2D(uSampler, vTextureCoord);
+    if (texColor.a < 0.1 || uColor.a < 0.1) discard;
+    
+    // Only cast shadows from the bottom 25% of the sprite
+    // This creates a footprint-based shadow in 2D top-down instead of a full-body shadow,
+    // which prevents objects (like trees) from heavily self-shadowing their own canopies
+    vec2 localUV = (vTextureCoord - uTexOffset) / uTexScale;
+    if (localUV.y < 0.75) discard;
+    
+    // Output pure black (with alpha) for the occlusion map.
+    // We encode the Z-depth of the occluder into the Red and Green channels to support depth-aware shadows.
+    // Z is mapped from [-10.0, 10.0] to [0.0, 1.0].
+    float normZ = clamp((vWorldPos.z + 10.0) / 20.0, 0.0, 1.0);
+    vec2 enc = vec2(1.0, 255.0) * normZ;
+    enc = fract(enc);
+    enc.x -= enc.y * (1.0/255.0);
+    
+    // We use Blue = 0.0 to indicate this is an occluder, since clear color is White (1.0, 1.0, 1.0, 1.0).
+    gl_FragColor = vec4(enc.x, enc.y, 0.0, 1.0);
+  }
+`;
+
+export class OcclusionMaterial extends Material {
+	constructor() {
+		// We can safely reuse the standard LIT_SPRITE_VS as it just passes position and scale
+		super(LIT_SPRITE_VS, OCCLUSION_FS);
+	}
+}

package/src/renderer/ParticleMaterial.ts

@@ -0,0 +1,66 @@
+import { Material } from "./Material";
+
+export const PARTICLE_VS = `
+  attribute vec4 aVertexPosition;
+  attribute vec2 aTextureCoord;
+  attribute vec4 aVertexColor; // Need color buffer mapped!
+
+  uniform mat4 uModelMatrix;
+  uniform mat4 uModelViewMatrix;
+  uniform mat4 uProjectionMatrix;
+  
+  varying highp vec2 vTextureCoord;
+  varying lowp vec4 vColor;
+
+  void main(void) {
+    // Note: since ParticleSystem calculates world or relative positions
+    // locally if it is handling billboarding, uModelViewMatrix covers camera projection cleanly
+    gl_Position = uProjectionMatrix * uModelViewMatrix * aVertexPosition;
+    vTextureCoord = aTextureCoord;
+    vColor = aVertexColor;
+  }
+`;
+
+export const PARTICLE_FS = `
+  precision mediump float;
+  
+  varying highp vec2 vTextureCoord;
+  varying lowp vec4 vColor;
+  
+  uniform sampler2D uSampler;
+  uniform int uUseTexture;
+  uniform int uShape; // 0: square, 1: circle
+
+  void main(void) {
+    vec4 texColor = vec4(1.0);
+    
+    if (uUseTexture == 1) {
+        texColor = texture2D(uSampler, vTextureCoord);
+    } else if (uShape == 1) {
+        // Procedural soft circle glow
+        vec2 center = vec2(0.5, 0.5);
+        float dist = distance(vTextureCoord, center);
+        
+        // Soft gradient fade based on distance (fixed undefined edge boundaries)
+        float glow = 1.0 - smoothstep(0.0, 0.5, dist);
+        texColor = vec4(1.0, 1.0, 1.0, glow);
+    }
+    
+    vec4 finalColor = texColor * vColor;
+    
+    if (finalColor.a < 0.01) discard;
+    
+    gl_FragColor = finalColor;
+  }
+`;
+
+export class ParticleMaterial extends Material {
+	constructor() {
+		super(PARTICLE_VS, PARTICLE_FS);
+		this.uniforms.uUseTexture = new Int32Array([0]);
+		this.uniforms.uShape = new Int32Array([1]); // default to circle
+		this.blendMode = "Additive";
+		this.depthTest = true;
+		this.depthWrite = false;
+	}
+}

package/src/renderer/Shader.ts

@@ -0,0 +1,44 @@
+export class Shader {
+	public program: WebGLProgram;
+
+	constructor(gl: WebGLRenderingContext, vsSource: string, fsSource: string) {
+		const vertexShader = this.compileShader(gl, gl.VERTEX_SHADER, vsSource);
+		const fragmentShader = this.compileShader(gl, gl.FRAGMENT_SHADER, fsSource);
+
+		const program = gl.createProgram();
+		if (!program) throw new Error("Failed to create WebGL program");
+
+		gl.attachShader(program, vertexShader);
+		gl.attachShader(program, fragmentShader);
+		gl.linkProgram(program);
+
+		if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
+			throw new Error(
+				"Unable to initialize the shader program: " +
+					gl.getProgramInfoLog(program),
+			);
+		}
+
+		this.program = program;
+	}
+
+	private compileShader(
+		gl: WebGLRenderingContext,
+		type: number,
+		source: string,
+	): WebGLShader {
+		const shader = gl.createShader(type);
+		if (!shader) throw new Error("Failed to create WebGL shader");
+
+		gl.shaderSource(shader, source);
+		gl.compileShader(shader);
+
+		if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
+            const info = gl.getShaderInfoLog(shader);
+            document.body.innerHTML += `<div style="color:red;font-size:24px;position:absolute;z-index:9999;top:0;left:0">${info}</div>`;
+			gl.deleteShader(shader);
+			throw new Error("An error occurred compiling the shaders: " + info);
+		}
+		return shader;
+	}
+}

package/src/renderer/SkinnedLitMaterial.ts

@@ -0,0 +1,55 @@
+import { LIT_SPRITE_FS, LIT_SPRITE_VS } from "./LitMaterial";
+import { Material } from "./Material";
+
+export const SKINNED_LIT_VS = `
+  attribute vec4 aVertexPosition;
+  attribute vec2 aTextureCoord;
+  attribute vec3 aVertexNormal;
+  
+  // Skinning variables
+  attribute vec4 aJoints;
+  attribute vec4 aWeights;
+  uniform mat4 uJointMatrices[64];
+
+  uniform mat4 uModelMatrix;
+  uniform mat4 uModelViewMatrix;
+  uniform mat4 uProjectionMatrix;
+  uniform vec2 uTexOffset;
+  uniform vec2 uTexScale;
+  
+  varying highp vec2 vTextureCoord;
+  varying highp vec3 vWorldPos;
+  varying highp vec3 vNormal;
+
+  void main(void) {
+    // 1. Calculate Skin Matrix
+    mat4 skinMatrix = 
+        aWeights.x * uJointMatrices[int(aJoints.x)] +
+        aWeights.y * uJointMatrices[int(aJoints.y)] +
+        aWeights.z * uJointMatrices[int(aJoints.z)] +
+        aWeights.w * uJointMatrices[int(aJoints.w)];
+
+    // 2. Skinned local position
+    vec4 localPos = skinMatrix * aVertexPosition;
+    
+    // 3. Final projection
+    gl_Position = uProjectionMatrix * uModelViewMatrix * localPos;
+    
+    vTextureCoord = (aTextureCoord * uTexScale) + uTexOffset;
+    
+    // Compute world position for lighting calculations
+    vWorldPos = (uModelMatrix * localPos).xyz;
+    
+    // Approximate normal transformation using ModelMatrix directly
+    // This is valid for Translation/Rotation uniform scaling
+    mat3 normalSkinMatrix = mat3(skinMatrix);
+    vNormal = normalize(mat3(uModelMatrix) * normalSkinMatrix * aVertexNormal);
+  }
+`;
+
+export class SkinnedLitMaterial extends Material {
+	constructor() {
+		// Uses the exact same Fragment Shader from LitMaterial for a unified lighting pipeline
+		super(SKINNED_LIT_VS, LIT_SPRITE_FS);
+	}
+}