---
name: godot-convert-shaders
version: 1.0.0
displayName: "Godot 3.x to 4.x Shader Converter"
description: >
  Converts Godot 3.x shader code to Godot 4.x shader syntax. Updates SCREEN_TEXTURE
  to screen_texture uniform, DEPTH_TEXTURE to depth_texture uniform, texture() function
  changes, built-in varyings updates, and light function signature changes. Essential
  for rendering and visual effect migrations.
author: "Asreonn"
license: MIT
category: game-development
type: tool
difficulty: advanced
audience: [developers, technical-artists, migrators]
keywords:
  - godot
  - shader
  - shaders
  - conversion
  - migration
  - godot3
  - godot4
  - screen_texture
  - depth_texture
  - texture
  - glsl
  - visual-effects
platforms: [macos, linux, windows]
repository: https://github.com/asreonn/godot-superpowers
homepage: https://github.com/asreonn/godot-superpowers#readme
filesystem:
  read:
    - "${PROJECT_ROOT}/**/*.gdshader"
    - "${PROJECT_ROOT}/**/*.shader"
    - "${PROJECT_ROOT}/project.godot"
  write:
    - "${PROJECT_ROOT}/**/*.gdshader"
    - "${PROJECT_ROOT}/**/*.shader"
  deny:
    - "**/.env*"
    - "**/secrets*"
    - "**/*.key"
behavior:
  timeout: 300
  retry: 2
  cache: true
  interactive: true
---

# Godot 3.x to 4.x Shader Converter

**Converts Godot 3.x shader code to Godot 4.x shader syntax.**

## Core Conversions

This skill performs five key shader modernizations:

| Godot 3.x | Godot 4.x | Type |
|-----------|-----------|------|
| `SCREEN_TEXTURE` | `uniform sampler2D screen_texture` | Screen sampling |
| `DEPTH_TEXTURE` | `uniform sampler2D depth_texture` | Depth sampling |
| `texture(SCREEN_TEXTURE, ...)` | `textureLod(screen_texture, ...)` | Texture sampling |
| `varying` → `VARIABLE` | `varying` → `variable` | Built-in varyings |
| `light()` signature | `light()` with new params | Light functions |

---

## UPON INVOCATION - START HERE

When this skill is invoked, IMMEDIATELY execute:

### 1. Verify Godot Project (5 seconds)

```bash
ls project.godot 2>/dev/null && echo "✓ Godot project detected" || echo "✗ Not a Godot project"
```

**If NOT a Godot project:**
- Inform user this skill only works on Godot projects
- STOP here

**If IS a Godot project:**
- Proceed to step 2

### 2. Detect Shader Files (10 seconds)

```bash
# Find all shader files
echo "=== Detecting Shader Files ==="
echo ".gdshader files (Godot 4.x format):"
find . -name "*.gdshader" -type f | wc -l

echo ".shader files (Godot 3.x format):"
find . -name "*.shader" -type f | wc -l
```

### 3. Detect Godot 3.x Patterns (15 seconds)

```bash
echo "=== Detecting Godot 3.x Shader Patterns ==="

echo "SCREEN_TEXTURE references:"
grep -rn "SCREEN_TEXTURE" --include="*.shader" --include="*.gdshader" . 2>/dev/null | wc -l

echo "DEPTH_TEXTURE references:"
grep -rn "DEPTH_TEXTURE" --include="*.shader" --include="*.gdshader" . 2>/dev/null | wc -l

echo "texture() with hint_screen_texture:"
grep -rn "hint_screen_texture" --include="*.shader" --include="*.gdshader" . 2>/dev/null | wc -l

echo "Built-in varying uppercase (VERTEX, UV, COLOR):"
grep -rn "^varying.*VERTEX\|^varying.*UV\|^varying.*COLOR" --include="*.shader" --include="*.gdshader" . 2>/dev/null | wc -l

echo "Light functions (light():"
grep -rn "^void light()" --include="*.shader" --include="*.gdshader" . 2>/dev/null | wc -l
echo "Light functions with old signature:"
grep -rn "light.*DIFFUSE\|light.*SPECULAR" --include="*.shader" --include="*.gdshader" . 2>/dev/null | wc -l
```

### 4. Present Findings

Show the user:
```
=== Godot 4.x Shader Conversion Analysis ===

Project: [project name]
Shaders to convert:
- .shader files (Godot 3.x): X
- .gdshader files: X

Patterns requiring conversion:
- SCREEN_TEXTURE usage: X
- DEPTH_TEXTURE usage: X
- hint_screen_texture uniforms: X
- Built-in varyings (uppercase): X
- Light function signatures: X

Total shaders to update: X

Conversion includes:
✓ SCREEN_TEXTURE → screen_texture uniform
✓ DEPTH_TEXTURE → depth_texture uniform
✓ texture() → textureLod() for screen/depth
✓ Varying built-ins → lowercase
✓ Light function parameters → new signature
✓ File extension .shader → .gdshader
✓ Git commit per file
✓ Backup before changes

Would you like me to:
1. Convert all shaders (recommended)
2. Show detailed breakdown first
3. Select specific conversions
4. Cancel
```

### 5. Wait for User Choice

- **If 1 (Proceed):** Start Phase 2 immediately
- **If 2 (Details):** Show file-by-file breakdown, then offer to proceed
- **If 3 (Selective):** Ask which conversions to apply
- **If 4 (Cancel):** Exit skill

---

## Phase 1: Analysis & Inventory

### 1.1 Create Shader Inventory

```bash
# Find all shader files (both .shader and .gdshader)
find . -name "*.shader" -o -name "*.gdshader" | sort > /tmp/shader_files.txt
wc -l /tmp/shader_files.txt
echo "shader files found"
```

### 1.2 Analyze Each Shader

For each shader file, detect patterns:

```bash
# Analyze patterns per file
for file in $(cat /tmp/shader_files.txt); do
    echo "=== $file ==="
    grep -c "SCREEN_TEXTURE" "$file" 2>/dev/null || echo 0
    grep -c "DEPTH_TEXTURE" "$file" 2>/dev/null || echo 0
    grep -c "hint_screen_texture" "$file" 2>/dev/null || echo 0
    grep -c "^void light()" "$file" 2>/dev/null || echo 0
    # Check if .shader extension (needs rename)
    [[ "$file" == *.shader ]] && echo "RENAME_NEEDED" || echo "EXTENSION_OK"
done
```

### 1.3 Create Conversion Plan

```
Shader Conversion Plan:
=======================

1. SCREEN_TEXTURE → screen_texture (X files)
2. DEPTH_TEXTURE → depth_texture (X files)
3. texture() → textureLod() (X files)
4. Built-in varyings lowercase (X files)
5. Light function signatures (X files)
6. File extension .shader → .gdshader (X files)

Total files to modify: X
Estimated time: Auto (user doesn't wait)
Backup created: YES (git tag)
Rollback available: YES
```

---

## Phase 2: Conversion Operations

### Conversion A: SCREEN_TEXTURE → screen_texture uniform

**Detection:**
```bash
grep -rn "SCREEN_TEXTURE" --include="*.shader" --include="*.gdshader" .
```

**Transformation Process:**

1. **Add uniform declaration at top of shader:**
   ```glsl
   // Add near top of file, after shader_type
   uniform sampler2D screen_texture : hint_screen_texture, filter_linear_mipmap;
   ```

2. **Replace SCREEN_TEXTURE references:**
   ```glsl
   // Before (Godot 3.x)
   vec4 screen_color = texture(SCREEN_TEXTURE, SCREEN_UV);
   
   // After (Godot 4.x)
   vec4 screen_color = textureLod(screen_texture, SCREEN_UV, 0.0);
   ```

**Mapping Table:**

| Godot 3.x | Godot 4.x |
|-----------|-----------|
| `SCREEN_TEXTURE` | `screen_texture` (uniform) |
| `texture(SCREEN_TEXTURE, uv)` | `textureLod(screen_texture, uv, 0.0)` |
| `texture(SCREEN_TEXTURE, uv, lod)` | `textureLod(screen_texture, uv, lod)` |

**Important:** Use `textureLod()` instead of `texture()` for screen and depth textures in Godot 4.x to ensure correct mipmap behavior.

---

### Conversion B: DEPTH_TEXTURE → depth_texture uniform

**Detection:**
```bash
grep -rn "DEPTH_TEXTURE" --include="*.shader" --include="*.gdshader" .
```

**Transformation Process:**

1. **Add uniform declaration at top of shader:**
   ```glsl
   // Add near top of file, after shader_type
   uniform sampler2D depth_texture : hint_depth_texture, filter_linear_mipmap;
   ```

2. **Replace DEPTH_TEXTURE references:**
   ```glsl
   // Before (Godot 3.x)
   float depth = texture(DEPTH_TEXTURE, SCREEN_UV).r;
   
   // After (Godot 4.x)
   float depth = textureLod(depth_texture, SCREEN_UV, 0.0).r;
   ```

**Mapping Table:**

| Godot 3.x | Godot 4.x |
|-----------|-----------|
| `DEPTH_TEXTURE` | `depth_texture` (uniform) |
| `texture(DEPTH_TEXTURE, uv)` | `textureLod(depth_texture, uv, 0.0)` |
| `texture(DEPTH_TEXTURE, uv, lod)` | `textureLod(depth_texture, uv, lod)` |

---

### Conversion C: texture() Function Changes

**Detection:**
```bash
grep -rn "texture(SCREEN_TEXTURE\|texture(DEPTH_TEXTURE" --include="*.shader" --include="*.gdshader" .
```

**Core Changes:**

Godot 4.x requires `textureLod()` for screen and depth textures to ensure explicit mipmap level control:

```glsl
// Godot 3.x - implicit LOD
vec4 color = texture(SCREEN_TEXTURE, uv);

// Godot 4.x - explicit LOD
uniform sampler2D screen_texture : hint_screen_texture, filter_linear_mipmap;
vec4 color = textureLod(screen_texture, uv, 0.0);
```

**Conversion Pattern:**

| Pattern | Replacement |
|---------|-------------|
| `texture(SCREEN_TEXTURE, UV)` | `textureLod(screen_texture, UV, 0.0)` |
| `texture(SCREEN_TEXTURE, UV, 2.0)` | `textureLod(screen_texture, UV, 2.0)` |
| `texture(DEPTH_TEXTURE, UV)` | `textureLod(depth_texture, UV, 0.0)` |
| `texture(DEPTH_TEXTURE, UV, lod)` | `textureLod(depth_texture, UV, lod)` |

---

### Conversion D: Built-in Varyings (Uppercase → Lowercase)

**Detection:**
```bash
grep -rn "^varying.*VERTEX\|^varying.*UV\|^varying.*COLOR\|^varying.*NORMAL" --include="*.shader" --include="*.gdshader" .
```

**Built-in Varying Changes:**

In Godot 3.x, built-in varyings like `VERTEX`, `UV`, `COLOR` were accessed as-is.
In Godot 4.x, when you declare your own `varying`, the built-ins become lowercase in the fragment shader.

**Mapping Table:**

| Declared Varying | Godot 3.x Fragment | Godot 4.x Fragment |
|------------------|-------------------|-------------------|
| `varying vec2 my_uv` | `my_uv` (unchanged) | `my_uv` (unchanged) |
| Built-in `VERTEX` | `VERTEX` | `vertex` |
| Built-in `UV` | `UV` | `uv` |
| Built-in `COLOR` | `COLOR` | `color` |
| Built-in `NORMAL` | `NORMAL` | `normal` |

**Important:** Only built-in varyings change to lowercase. User-declared varyings keep their original case.

**Example:**
```glsl
// Before (Godot 3.x)
shader_type spatial;
varying vec2 custom_uv;

void vertex() {
    custom_uv = UV;  // UV is uppercase built-in
    VERTEX.y += 1.0; // VERTEX is uppercase
}

void fragment() {
    ALBEDO = texture(TEXTURE, custom_uv).rgb;
    if (VERTEX.y > 0.0) {  // VERTEX still uppercase in vertex(), but...
        // In Godot 4.x, would be 'vertex' in fragment()
    }
}

// After (Godot 4.x)
shader_type spatial;
varying vec2 custom_uv;

void vertex() {
    custom_uv = uv;  // uv is lowercase built-in
    vertex.y += 1.0; // vertex is lowercase
}

void fragment() {
    ALBEDO = texture(TEXTURE, custom_uv).rgb;  // custom_uv unchanged
    if (vertex.y > 0.0) {  // vertex is lowercase in fragment()
        
    }
}
```

---

### Conversion E: Light Function Signature Changes

**Detection:**
```bash
grep -rn "^void light()" --include="*.shader" --include="*.gdshader" .
grep -rn "light.*DIFFUSE\|light.*SPECULAR\|light.*ATTENUATION" --include="*.shader" --include="*.gdshader" .
```

**Light Function Changes:**

Godot 4.x changes how light calculations are accessed within the `light()` function.

**Mapping Table:**

| Godot 3.x | Godot 4.x |
|-----------|-----------|
| `DIFFUSE` | `diffuse_light` |
| `SPECULAR` | `specular_light` |
| `ATTENUATION` | `attenuation` |
| `SHADOW_ATTENUATION` | `shadow_attenuation` |

**Complete Example:**

```glsl
// Before (Godot 3.x)
shader_type spatial;

void light() {
    DIFFUSE = ALBEDO * ATTENUATION;
    SPECULAR = vec3(0.5) * pow(max(dot(NORMAL, LIGHT), 0.0), 32.0) * ATTENUATION;
}

// After (Godot 4.x)
shader_type spatial;

void light() {
    diffuse_light = ALBEDO * attenuation;
    specular_light = vec3(0.5) * pow(max(dot(normal, LIGHT), 0.0), 32.0) * attenuation;
}
```

**Light Function Parameter Changes:**

```glsl
// Godot 3.x - no parameters
void light() {
    // Access global light properties
}

// Godot 4.x - accepts light index (for multi-light)
void light(int light_index) {
    // Access light properties via LIGHT, attenuation, etc.
}
```

---

### Conversion F: File Extension (.shader → .gdshader)

**Detection:**
```bash
find . -name "*.shader" -type f | grep -v ".gdshader"
```

**Transformation:**
Rename files from `.shader` to `.gdshader`:

```bash
# Rename all .shader files to .gdshader
for file in $(find . -name "*.shader" -type f); do
    newname="${file%.shader}.gdshader"
    mv "$file" "$newname"
    echo "Renamed: $file → $newname"
done
```

**Note:** Godot 4.x uses `.gdshader` extension exclusively. `.shader` files from Godot 3.x should be renamed.

---

## Phase 3: Execution & Safety

### 3.1 Create Git Baseline

```bash
# Create backup tag
git tag shader-baseline-$(date +%Y%m%d-%H%M%S)

# Stage any current changes
git add .
git commit -m "Baseline: Pre-shader conversion" || echo "No changes to commit"
```

### 3.2 Process Files Sequentially

For each shader file:

```bash
# Read and process shader content
python3 << 'EOF'
import re
import sys

def convert_shader(content, filename):
    original = content
    conversions_applied = []
    
    # Conversion 1: Add screen_texture uniform if SCREEN_TEXTURE is used
    if 'SCREEN_TEXTURE' in content and 'uniform sampler2D screen_texture' not in content:
        # Find shader_type line and add uniform after it
        content = re.sub(
            r'(shader_type\s+\w+;\n?)',
            r'\1\nuniform sampler2D screen_texture : hint_screen_texture, filter_linear_mipmap;\n',
            content
        )
        conversions_applied.append("Added screen_texture uniform")
    
    # Conversion 2: Add depth_texture uniform if DEPTH_TEXTURE is used
    if 'DEPTH_TEXTURE' in content and 'uniform sampler2D depth_texture' not in content:
        content = re.sub(
            r'(shader_type\s+\w+;\n?)',
            r'\1\nuniform sampler2D depth_texture : hint_depth_texture, filter_linear_mipmap;\n',
            content
        )
        conversions_applied.append("Added depth_texture uniform")
    
    # Conversion 3: SCREEN_TEXTURE → screen_texture in texture() calls
    if 'texture(SCREEN_TEXTURE' in content or 'textureLod(screen_texture' in content:
        # Replace texture(SCREEN_TEXTURE, ...) with textureLod(screen_texture, ..., 0.0)
        content = re.sub(
            r'texture\s*\(\s*SCREEN_TEXTURE\s*,\s*([^,\)]+)\s*\)',
            r'textureLod(screen_texture, \1, 0.0)',
            content
        )
        # Replace texture(SCREEN_TEXTURE, ..., lod) with textureLod(screen_texture, ..., lod)
        content = re.sub(
            r'texture\s*\(\s*SCREEN_TEXTURE\s*,\s*([^,\)]+)\s*,\s*([^\)]+)\s*\)',
            r'textureLod(screen_texture, \1, \2)',
            content
        )
        # Replace remaining SCREEN_TEXTURE references
        content = content.replace('SCREEN_TEXTURE', 'screen_texture')
        conversions_applied.append("Converted SCREEN_TEXTURE to screen_texture")
    
    # Conversion 4: DEPTH_TEXTURE → depth_texture
    if 'texture(DEPTH_TEXTURE' in content or 'textureLod(depth_texture' in content:
        content = re.sub(
            r'texture\s*\(\s*DEPTH_TEXTURE\s*,\s*([^,\)]+)\s*\)',
            r'textureLod(depth_texture, \1, 0.0)',
            content
        )
        content = re.sub(
            r'texture\s*\(\s*DEPTH_TEXTURE\s*,\s*([^,\)]+)\s*,\s*([^\)]+)\s*\)',
            r'textureLod(depth_texture, \1, \2)',
            content
        )
        content = content.replace('DEPTH_TEXTURE', 'depth_texture')
        conversions_applied.append("Converted DEPTH_TEXTURE to depth_texture")
    
    # Conversion 5: Light function variables (only in light() function)
    if 'void light()' in content:
        # Replace light variables
        content = content.replace('DIFFUSE', 'diffuse_light')
        content = content.replace('SPECULAR', 'specular_light')
        content = content.replace('ATTENUATION', 'attenuation')
        conversions_applied.append("Converted light function variables")
    
    # Conversion 6: Built-in varyings in fragment() function (lowercase)
    # This is complex - only affect fragment() scope
    if 'void fragment()' in content:
        # Find fragment function and convert built-in varyings there
        fragment_start = content.find('void fragment()')
        if fragment_start != -1:
            # Find the end of fragment function (next void or end of file)
            fragment_end = len(content)
            next_func = re.search(r'\nvoid\s+\w+\s*\(\)', content[fragment_start+1:])
            if next_func:
                fragment_end = fragment_start + 1 + next_func.start()
            
            fragment_section = content[fragment_start:fragment_end]
            # Convert built-ins in fragment only
            fragment_section = re.sub(r'\bVERTEX\b', 'vertex', fragment_section)
            fragment_section = re.sub(r'\bUV\b', 'uv', fragment_section)
            fragment_section = re.sub(r'\bCOLOR\b', 'color', fragment_section)
            fragment_section = re.sub(r'\bNORMAL\b', 'normal', fragment_section)
            
            content = content[:fragment_start] + fragment_section + content[fragment_end:]
            conversions_applied.append("Converted built-in varyings to lowercase in fragment()")
    
    return content, conversions_applied

# Process file
filename = sys.argv[1] if len(sys.argv) > 1 else "shader.gdshader"
with open(filename, 'r') as f:
    content = f.read()

new_content, conversions = convert_shader(content, filename)

with open(filename, 'w') as f:
    f.write(new_content)

print(f"Applied {len(conversions)} conversions:")
for c in conversions:
    print(f"  - {c}")
EOF
```

### 3.3 Rename File Extensions

```bash
# Rename .shader to .gdshader after conversion
for file in $(find . -name "*.shader" -type f); do
    if [[ "$file" != *.gdshader ]]; then
        newname="${file%.shader}.gdshader"
        mv "$file" "$newname"
        git add "$newname"
        git rm "$file" 2>/dev/null || echo "Old file: $file (deleted)"
    fi
done
```

### 3.4 Commit Per File

```bash
# After each file modification
git add "$file"
git commit -m "Convert shader: $file to Godot 4.x

- Updated texture sampling (SCREEN_TEXTURE/DEPTH_TEXTURE)
- Added uniform declarations with hints
- Converted texture() to textureLod()
- Updated built-in varyings to lowercase
- Fixed light function variables
- Renamed extension to .gdshader"
```

---

## Phase 4: Verification & Testing

### 4.1 Syntax Validation

```bash
# Check all modified shaders for syntax errors
echo "=== Validating Shader Syntax ==="
for file in $(git diff --name-only HEAD~10..HEAD | grep "\.gdshader$"); do
    echo "Checking $file..."
    # Godot can validate shaders by loading them
    godot --headless --quit-after 2 project.godot 2>&1 | grep -i "$file" && echo "Warning: Possible issue in $file"
done
```

### 4.2 Pattern Verification

```bash
echo "=== Verifying Godot 3.x Patterns Removed ==="

echo "SCREEN_TEXTURE references remaining:"
grep -rn "SCREEN_TEXTURE" --include="*.gdshader" . 2>/dev/null | wc -l

echo "DEPTH_TEXTURE references remaining:"
grep -rn "DEPTH_TEXTURE" --include="*.gdshader" . 2>/dev/null | wc -l

echo "texture(SCREEN_TEXTURE remaining:"
grep -rn "texture\s*(\s*SCREEN_TEXTURE" --include="*.gdshader" . 2>/dev/null | wc -l

echo "Godot 3.x light variables (DIFFUSE/SPECULAR) remaining:"
grep -rn "\bDIFFUSE\b\|\bSPECULAR\b" --include="*.gdshader" . 2>/dev/null | wc -l

echo ".shader files (should be 0):"
find . -name "*.shader" -type f | grep -v ".gdshader" | wc -l
```

### 4.3 Godot Project Test

```bash
# Open project in Godot to verify shaders compile
echo "=== Testing in Godot ==="
godot --editor project.godot &
sleep 5

# Check Output panel for shader errors
# (User should visually verify no shader-related errors)
```

---

## Examples

### Example 1: Screen Distortion Shader

**Before (Godot 3.x):**
```glsl
shader_type canvas_item;

uniform float distortion_strength : hint_range(0.0, 1.0) = 0.1;

void fragment() {
    vec2 distorted_uv = SCREEN_UV + (UV - 0.5) * distortion_strength;
    vec4 screen_color = texture(SCREEN_TEXTURE, distorted_uv);
    COLOR = screen_color;
}
```

**After (Godot 4.x):**
```glsl
shader_type canvas_item;

uniform sampler2D screen_texture : hint_screen_texture, filter_linear_mipmap;
uniform float distortion_strength : hint_range(0.0, 1.0) = 0.1;

void fragment() {
    vec2 distorted_uv = SCREEN_UV + (uv - 0.5) * distortion_strength;
    vec4 screen_color = textureLod(screen_texture, distorted_uv, 0.0);
    COLOR = screen_color;
}
```

### Example 2: Depth-Based Fog Shader

**Before (Godot 3.x):**
```glsl
shader_type spatial;
render_mode depth_draw_opaque, cull_disabled;

uniform vec4 fog_color : source_color = vec4(0.5, 0.6, 0.7, 1.0);
uniform float fog_density : hint_range(0.0, 1.0) = 0.1;

void fragment() {
    float depth = texture(DEPTH_TEXTURE, SCREEN_UV).r;
    float fog_factor = exp(-fog_density * depth);
    
    ALBEDO = fog_color.rgb;
    ALPHA = 1.0 - fog_factor;
}
```

**After (Godot 4.x):**
```glsl
shader_type spatial;
render_mode depth_draw_opaque, cull_disabled;

uniform sampler2D depth_texture : hint_depth_texture, filter_linear_mipmap;
uniform vec4 fog_color : source_color = vec4(0.5, 0.6, 0.7, 1.0);
uniform float fog_density : hint_range(0.0, 1.0) = 0.1;

void fragment() {
    float depth = textureLod(depth_texture, SCREEN_UV, 0.0).r;
    float fog_factor = exp(-fog_density * depth);
    
    ALBEDO = fog_color.rgb;
    ALPHA = 1.0 - fog_factor;
}
```

### Example 3: Custom Light Shader

**Before (Godot 3.x):**
```glsl
shader_type spatial;

uniform vec4 highlight_color : source_color = vec4(1.0, 0.8, 0.0, 1.0);

void fragment() {
    ALBEDO = vec3(0.5);
}

void light() {
    float dot_product = max(dot(NORMAL, LIGHT), 0.0);
    
    if (dot_product > 0.9) {
        DIFFUSE = highlight_color.rgb * ATTENUATION;
    } else {
        DIFFUSE = ALBEDO * dot_product * ATTENUATION;
    }
    
    SPECULAR = vec3(0.0);
}
```

**After (Godot 4.x):**
```glsl
shader_type spatial;

uniform vec4 highlight_color : source_color = vec4(1.0, 0.8, 0.0, 1.0);

void fragment() {
    ALBEDO = vec3(0.5);
}

void light() {
    float dot_product = max(dot(normal, LIGHT), 0.0);
    
    if (dot_product > 0.9) {
        diffuse_light = highlight_color.rgb * attenuation;
    } else {
        diffuse_light = ALBEDO * dot_product * attenuation;
    }
    
    specular_light = vec3(0.0);
}
```

### Example 4: Vertex Displacement Shader

**Before (Godot 3.x):**
```glsl
shader_type spatial;

uniform float wave_height : hint_range(0.0, 2.0) = 0.5;
uniform float wave_speed : hint_range(0.0, 10.0) = 2.0;

void vertex() {
    float wave = sin(VERTEX.x * 2.0 + TIME * wave_speed) * wave_height;
    VERTEX.y += wave;
}

void fragment() {
    vec2 uv_offset = UV * 2.0;
    ALBEDO = vec3(uv_offset, 0.5);
}
```

**After (Godot 4.x):**
```glsl
shader_type spatial;

uniform float wave_height : hint_range(0.0, 2.0) = 0.5;
uniform float wave_speed : hint_range(0.0, 10.0) = 2.0;

void vertex() {
    float wave = sin(vertex.x * 2.0 + TIME * wave_speed) * wave_height;
    vertex.y += wave;
}

void fragment() {
    vec2 uv_offset = uv * 2.0;
    ALBEDO = vec3(uv_offset, 0.5);
}
```

---

## Complete Conversion Mapping Reference

### Texture Uniforms

| Godot 3.x | Godot 4.x Declaration | Godot 4.x Usage |
|-----------|----------------------|----------------|
| `SCREEN_TEXTURE` | `uniform sampler2D screen_texture : hint_screen_texture, filter_linear_mipmap;` | `textureLod(screen_texture, uv, lod)` |
| `DEPTH_TEXTURE` | `uniform sampler2D depth_texture : hint_depth_texture, filter_linear_mipmap;` | `textureLod(depth_texture, uv, lod)` |

### Texture Sampling Functions

| Godot 3.x | Godot 4.x |
|-----------|-----------|
| `texture(SCREEN_TEXTURE, uv)` | `textureLod(screen_texture, uv, 0.0)` |
| `texture(SCREEN_TEXTURE, uv, lod)` | `textureLod(screen_texture, uv, lod)` |
| `texture(DEPTH_TEXTURE, uv)` | `textureLod(depth_texture, uv, 0.0)` |
| `texture(TEXTURE, uv)` | `texture(TEXTURE, uv)` (unchanged) |
| `texture(NORMAL_TEXTURE, uv)` | `texture(NORMAL_TEXTURE, uv)` (unchanged) |

### Built-in Varyings (fragment() scope only)

| Godot 3.x | Godot 4.x |
|-----------|-----------|
| `VERTEX` | `vertex` |
| `UV` | `uv` |
| `COLOR` | `color` |
| `NORMAL` | `normal` |
| `TANGENT` | `tangent` |
| `BINORMAL` | `binormal` |

### Light Function Variables

| Godot 3.x | Godot 4.x |
|-----------|-----------|
| `DIFFUSE` | `diffuse_light` |
| `SPECULAR` | `specular_light` |
| `ATTENUATION` | `attenuation` |
| `SHADOW_ATTENUATION` | `shadow_attenuation` |

---

## Success Criteria

Conversion complete when:

- ✓ Zero `SCREEN_TEXTURE` references remain (converted to uniform)
- ✓ Zero `DEPTH_TEXTURE` references remain (converted to uniform)
- ✓ All `texture()` calls for screen/depth use `textureLod()`
- ✓ Built-in varyings in `fragment()` are lowercase
- ✓ Light function uses new variable names (`diffuse_light`, `specular_light`, etc.)
- ✓ All `.shader` files renamed to `.gdshader`
- ✓ Uniform declarations include proper hints (`hint_screen_texture`, `hint_depth_texture`)
- ✓ All shaders compile without errors in Godot 4.x
- ✓ Visual output matches Godot 3.x behavior
- ✓ Git history shows clear conversion commits

---

## Common Issues & Solutions

### Issue 1: texture() vs textureLod()

**Problem:**
```glsl
// Won't work in Godot 4.x
vec4 color = texture(screen_texture, UV);
```

**Solution:**
```glsl
// Correct Godot 4.x syntax
vec4 color = textureLod(screen_texture, UV, 0.0);
```

**Explanation:** Godot 4.x requires explicit LOD for screen and depth textures. Always use `textureLod()` with an explicit LOD value (0.0 for no mipmapping).

### Issue 2: Missing Uniform Declarations

**Problem:**
```glsl
shader_type canvas_item;

void fragment() {
    COLOR = textureLod(screen_texture, UV, 0.0);  // ERROR: screen_texture not declared
}
```

**Solution:**
```glsl
shader_type canvas_item;

uniform sampler2D screen_texture : hint_screen_texture, filter_linear_mipmap;

void fragment() {
    COLOR = textureLod(screen_texture, uv, 0.0);
}
```

**Explanation:** Godot 3.x provided SCREEN_TEXTURE implicitly. Godot 4.x requires explicit uniform declarations with hints.

### Issue 3: Wrong Case in Built-in Varyings

**Problem:**
```glsl
void fragment() {
    ALBEDO = texture(TEXTURE, UV).rgb;  // ERROR in Godot 4.x
}
```

**Solution:**
```glsl
void fragment() {
    ALBEDO = texture(TEXTURE, uv).rgb;  // Lowercase in fragment()
}
```

**Note:** Built-in varyings remain uppercase in `vertex()` but become lowercase in `fragment()` in Godot 4.x.

### Issue 4: Light Function Variable Names

**Problem:**
```glsl
void light() {
    DIFFUSE = ALBEDO;  // ERROR: DIFFUSE doesn't exist
}
```

**Solution:**
```glsl
void light() {
    diffuse_light = ALBEDO;  // Correct variable name
}
```

### Issue 5: Multiple hint declarations

**Problem:**
```glsl
uniform sampler2D screen_texture : hint_screen_texture;
uniform sampler2D depth_texture : hint_depth_texture;

// Later in code, trying to use both
```

**Issue:** If shader already has uniforms declared, don't duplicate them.

**Solution:** Check for existing declarations before adding.

---

## Rollback Procedure

If conversion causes issues:

```bash
# Find baseline tag
git tag | grep "shader-baseline"

# Reset to pre-conversion state
git reset --hard <baseline-tag>

# Or revert specific commits
git revert <conversion-commit-hash>

# Rename files back if needed
for file in $(find . -name "*.gdshader" -type f); do
    if [ ! -f "${file%.gdshader}.shader" ]; then
        mv "$file" "${file%.gdshader}.shader"
    fi
done
```

---

## Integration with Other Skills

**Use before:**
- `godot-modernize-gdscript` - Update shaders first, then scripts
- `godot-migrate-tilemap` - Visual effects often tied to tilemaps

**Use after:**
- Project conversion from Godot 3.x to 4.x
- `godot-organize-assets` - Organize shader files first

---

**This skill automates the tedious parts of Godot 3.x to 4.x shader migration while preserving exact visual output.**