| 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)
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:
2. Detect Shader Files (10 seconds)
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)
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
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:
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
[[ "$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:
grep -rn "SCREEN_TEXTURE" --include="*.shader" --include="*.gdshader" .
Transformation Process:
-
Add uniform declaration at top of shader:
// Add near top of file, after shader_type
uniform sampler2D screen_texture : hint_screen_texture, filter_linear_mipmap;
-
Replace SCREEN_TEXTURE references:
// 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:
grep -rn "DEPTH_TEXTURE" --include="*.shader" --include="*.gdshader" .
Transformation Process:
-
Add uniform declaration at top of shader:
// Add near top of file, after shader_type
uniform sampler2D depth_texture : hint_depth_texture, filter_linear_mipmap;
-
Replace DEPTH_TEXTURE references:
// 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:
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:
// 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:
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:
// 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:
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:
// 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:
// 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:
find . -name "*.shader" -type f | grep -v ".gdshader"
Transformation:
Rename files from .shader 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
git tag shader-baseline-$(date +%Y%m%d-%H%M%S)
git add .
git commit -m "Baseline: Pre-shader conversion" || echo "No changes to commit"
3.2 Process Files Sequentially
For each shader file:
python3 << 'EOF'
import re
import sys
def convert_shader(content, filename):
original = content
conversions_applied = []
if 'SCREEN_TEXTURE' in content and 'uniform sampler2D screen_texture' not in content:
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")
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")
if 'texture(SCREEN_TEXTURE' in content or 'textureLod(screen_texture' in content:
content = re.sub(
r'texture\s*\(\s*SCREEN_TEXTURE\s*,\s*([^,\)]+)\s*\)',
r'textureLod(screen_texture, \1, 0.0)',
content
)
content = re.sub(
r'texture\s*\(\s*SCREEN_TEXTURE\s*,\s*([^,\)]+)\s*,\s*([^\)]+)\s*\)',
r'textureLod(screen_texture, \1, \2)',
content
)
content = content.replace('SCREEN_TEXTURE', 'screen_texture')
conversions_applied.append("Converted SCREEN_TEXTURE to screen_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")
if 'void light()' in content:
content = content.replace('DIFFUSE', 'diffuse_light')
content = content.replace('SPECULAR', 'specular_light')
content = content.replace('ATTENUATION', 'attenuation')
conversions_applied.append("Converted light function variables")
if 'void fragment()' in content:
fragment_start = content.find('void fragment()')
if fragment_start != -1:
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]
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
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
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
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
echo "=== Validating Shader Syntax ==="
for file in $(git diff --name-only HEAD~10..HEAD | grep "\.gdshader$"); do
echo "Checking $file..."
godot --headless --quit-after 2 project.godot 2>&1 | grep -i "$file" && echo "Warning: Possible issue in $file"
done
4.2 Pattern Verification
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
echo "=== Testing in Godot ==="
godot --editor project.godot &
sleep 5
Examples
Example 1: Screen Distortion Shader
Before (Godot 3.x):
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):
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):
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):
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):
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):
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):
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):
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:
// Won't work in Godot 4.x
vec4 color = texture(screen_texture, UV);
Solution:
// 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:
shader_type canvas_item;
void fragment() {
COLOR = textureLod(screen_texture, UV, 0.0); // ERROR: screen_texture not declared
}
Solution:
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:
void fragment() {
ALBEDO = texture(TEXTURE, UV).rgb; // ERROR in Godot 4.x
}
Solution:
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:
void light() {
DIFFUSE = ALBEDO; // ERROR: DIFFUSE doesn't exist
}
Solution:
void light() {
diffuse_light = ALBEDO; // Correct variable name
}
Issue 5: Multiple hint declarations
Problem:
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:
git tag | grep "shader-baseline"
git reset --hard <baseline-tag>
git revert <conversion-commit-hash>
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 scriptsgodot-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.
