Srib view

srib-view

Project: SRIB — Godot 4.6 Android application with a 3D SmartThings home view. Role: Rendering and visual layer. Everything about how the 3D home scene looks.

---

Invocation

srib-view SRIB-NNN

Read issues/SRIB-NNN.md for the full spec. If no ticket is given, ask the user to describe the visual feature and confirm the scope before implementing.

---

The 3-Tier Shader System

This project organises shaders into three tiers. Identify which tier a new feature belongs to before writing any code.

Tier	Purpose	Examples	File location
Tier 1 — Base material	Per-object surface appearance: color, roughness, metallic, emissive	Wall paint, floor texture, furniture base coat	generated_shaders/tier1_<object>.gdshader
Tier 2 — State overlay	SmartThings device state reflected in appearance: on/off, active, alert	Light on = warm emissive, door open = highlight ring, leak = pulse	generated_shaders/tier2_<device>_state.gdshader
Tier 3 — Post-FX / global	Scene-wide effects: ambient glow, depth of field, vignette, color grade	Night mode, focus highlight, selection outline	generated_shaders/tier3_<effect>.gdshader or existing shaders/

When in doubt, ask: does this affect one object (Tier 1), reflect device state (Tier 2), or change the whole scene (Tier 3)?

---

Workflow

Step 1 — Read the ticket and locate relevant files

cat issues/SRIB-NNN.md
find . -name "*.gdshader" | head -40
find . -name "*.tres" | head -20   # ShaderMaterial resources

Identify: which MeshInstance3D or CanvasItem uses this shader, which .tres material file wraps it, and which scene (.tscn) contains the node.

Step 2 — Understand the existing shader

Read the shader file before modifying it. Note:

• Existing uniform declarations — any new uniform must not collide
• Which rendering mode (spatial, canvas_item, particles)
• Whether it uses FRAGMENT, VERTEX, or both

Step 3 — Implement the change

GDShader structure:

shader_type spatial;
render_mode blend_mix, depth_draw_opaque, cull_back, diffuse_burley, specular_schlick_ggx;

// Uniforms — driven by srib-integration via set_shader_parameter()
uniform vec4 base_color : source_color = vec4(1.0);
uniform float emissive_strength : hint_range(0.0, 5.0) = 0.0;
uniform float roughness : hint_range(0.0, 1.0) = 0.5;

void fragment() {
    ALBEDO = base_color.rgb;
    EMISSION = base_color.rgb * emissive_strength;
    ROUGHNESS = roughness;
}

Mobile GPU rules (Android GLES3 / Vulkan Mobile):

• Use lowp or mediump precision qualifiers on non-critical floats to save ALU cycles
• Avoid discard in fragment shaders — breaks early-z on Mali/Adreno
• Avoid dynamic array indexing; unroll loops manually when N ≤ 4
• Texture samples: use hint_default_white / hint_normal hints so the editor provides defaults
• Max 4 texture samples per fragment shader on low-end targets
• No varying arrays — use vec4 packing

Naming conventions:

• Shader file: tier<N>_<object_or_effect>_<variant>.gdshader
• Uniform names: snake_case, descriptive (e.g., emissive_strength not e)
• ShaderMaterial resource: same base name, .tres extension

Step 4 — Create or update the ShaderMaterial resource

If a .tres file already exists for this material, update it. If not, create one:

[gd_resource type="ShaderMaterial" load_steps=2 format=3]

[ext_resource type="Shader" path="res://generated_shaders/tier2_light_state.gdshader" id="1_abc"]

[resource]
shader = ExtResource("1_abc")
shader_parameter/base_color = Color(1, 1, 1, 1)
shader_parameter/emissive_strength = 0.0

Step 5 — Test the visual

1. Open the relevant scene in the Godot editor
2. Play Scene (F6) — check Output panel for shader errors
3. Verify the visual matches the acceptance criteria screenshot or description
4. Check on mobile: shader errors that are silent on desktop often crash on Android (wrong precision, missing extension)

---

Common shader patterns for SRIB

Device ON/OFF state (Tier 2)

uniform float device_on : hint_range(0.0, 1.0) = 0.0;
uniform vec4 on_color : source_color = vec4(1.0, 0.9, 0.6, 1.0);  // warm white
uniform vec4 off_color : source_color = vec4(0.2, 0.2, 0.2, 1.0);

void fragment() {
    ALBEDO = mix(off_color.rgb, on_color.rgb, device_on);
    EMISSION = on_color.rgb * device_on * 1.5;
}

Pulse / breathing effect (Tier 2, driven by model)

uniform float pulse_phase : hint_range(0.0, 1.0) = 0.0;  // set every frame by model
uniform vec4 pulse_color : source_color = vec4(1.0, 0.3, 0.1, 1.0);

void fragment() {
    float intensity = pulse_phase;  // model handles the sine wave
    EMISSION = pulse_color.rgb * intensity;
}

Selection / hover highlight (Tier 3 via outline)

Use Godot's built-in next_pass with a back-face cull-front shader for an outline effect. See existing shaders/ for the project's existing outline shader if one exists.

Two-tone shadow (existing in project)

The project has furniture_two_tone_shadow shader — extend rather than replace when adding furniture visual states.

---

Acceptance checklist

• Shader compiles without errors (Output panel clean)
• Visual matches the ticket description / screenshot
• No new uniforms shadow existing ones (check all .tres that use this shader)
• Tested on Play Scene (F6) in editor
• Tested on Android (or confirmed mobile-safe precision qualifiers)
• ShaderMaterial .tres updated with any new uniform defaults
• No regressions in other scenes using the same shader