Webgl Card Effects

WebGL Card Effects Skill

Overview

This skill adds GPU-accelerated visual effects to React card components using standalone WebGL2 fragment shaders — no Three.js, no R3F, no external library required. It targets deckbuilder games and card UIs where rarity tiers should feel visually distinct, not just differentiated by a CSS box-shadow value.

Scope: Holographic foil overlays, metallic shimmer bands, rarity-driven energy pulses, and interactive tilt-shine effects mounted directly on React card components. The canonical target is FramedCard.tsx in a React 19 / Vite / Tailwind project with a rarity system (starter → common → uncommon → rare → legendary).

Not in scope: 3D transformations, texture loading, post-processing pipelines, or any Three.js scene management. For those, use threejs-builder.

Key constraint: Browsers cap WebGL contexts at roughly 8–16 total per page. This skill uses a single shared WebGL2 context with blit-to-2D-canvas output per card, avoiding the per-card context problem entirely. See references/shader-integration-react.md for the full singleton pattern.

Instructions

Phase 1: ASSESS

Goal: Understand which effects are needed and confirm the card component structure before writing any code.

Step 1: Read the card component

Read these files before writing anything:

• src/components/cards/FramedCard.tsx — component structure, hover state, rarity prop flow
• src/components/cards/cardStyles.ts — CARD_SIZE_CONFIG for pixel dimensions, rarity string values

Confirm:

• How rarity reaches the component (prop name, TypeScript type, exact string values)
• Whether isHovered state already exists in the component
• Which sizes are rendered in contexts that justify shader cost (xl/lg only — xs/sm are too small)
• Whether showShine / card-shine CSS exists and needs coordination

Step 2: Select effect tier per rarity

Step 3: Confirm React version

Check package.json for the React version. This skill assumes React 19 (ref as prop, no forwardRef). If the project uses React 18, canvas refs require useRef + standard ref passing.

Gate: Rarity values confirmed, CARD_SIZE_CONFIG read, effect tiers decided. Proceed only when this gate passes.

Phase 2: BUILD

Goal: Write working GLSL shaders and the WebGL initialization harness.

Load references/card-shader-patterns.md now.

Step 1: Create the shader strings module

Create src/components/cards/effects/cardShaders.ts. This file holds:

• The shared vertex shader (passthrough UV coordinates)
• Three fragment shader strings: SHIMMER_FRAG, RARE_FRAG, LEGENDARY_FRAG
• A rarityToUniform(rarity: string): number mapping function

Every shader must expose this exact uniform interface:

uniform float u_time;        // seconds elapsed, JS wraps at 1000.0
uniform float u_rarity;      // 0.0=starter/common, 0.25=uncommon, 0.5=rare, 1.0=legendary
uniform float u_hover;       // 0.0 to 1.0, lerped by JavaScript each frame
uniform vec2  u_mouse;       // normalized card-space [0,1] mouse position
uniform vec2  u_resolution;  // canvas pixel dimensions (width, height)
uniform float u_upgraded;    // 0.0 or 1.0 — upgraded cards get slightly more intense effect

Step 2: Create the WebGL harness hook

Create src/components/cards/effects/useCardShader.ts.

Load references/shader-integration-react.md for the full hook source. The hook must:

• Use the shared WebGL2 context singleton (not create a new context per card)
• Accept { rarity, isHovered, isUpgraded, enabled } as input
• Return a RefObject<HTMLCanvasElement> that the component attaches to the canvas element
• Pause the animation loop when the card is off-screen (IntersectionObserver)
• Run at 30fps maximum via delta-time throttle
• Clean up the RAF loop and observer on unmount

Step 3: Shader construction for each tier

Load references/balatro-shader-breakdown.md for the legendary holographic shader GLSL source.

For rare: use the shimmer band + hue shift layer from the breakdown, omit the rainbow foil layer.

For uncommon: use only the metallic band pass (single moving highlight), opacity 0.3 maximum.

Gate: Run npx tsc --noEmit. Zero TypeScript errors. Open browser console and verify gl.getShaderInfoLog() returns empty string for all shaders.

Phase 3: INTEGRATE

Goal: Mount the canvas overlay on FramedCard.tsx and wire rarity/hover state into the shader uniforms.

Step 1: Derive render decision

Inside FramedCard, after the existing const shouldShine line:

const shouldRenderShader =
  ['uncommon', 'rare', 'legendary'].includes(rarity) &&
  size !== 'xs' &&
  size !== 'sm';

Step 2: Call the hook

const shaderCanvasRef = useCardShader({
  rarity,
  isHovered,
  isUpgraded,
  enabled: shouldRenderShader,
});

Step 3: Add the canvas overlay to JSX

Inside the motion.div return, immediately after the frame <img> element (after z-10):

{shouldRenderShader && (
  <canvas
    ref={shaderCanvasRef}
    className="absolute inset-0 w-full h-full pointer-events-none rounded-lg"
    style={{ zIndex: 15, mixBlendMode: 'screen' }}
  />
)}

mix-blend-mode: screen makes the shader's black background transparent while letting bright holographic colors add onto the card surface.

Step 4: Coordinate with existing CSS shine

The existing card-shine CSS class creates a gradient sweep on hover. It will double-shimmer with the WebGL effect. Suppress it for rarities that have the WebGL shader:

const shineClass =
  showShine && shouldShine && !shouldRenderShader
    ? `card-shine ${...}`
    : '';

Step 5: Verify z-layer stack

From bottom to top inside the card:

• z-0 — artwork container
• z-10 — frame PNG image
• z-15 — shader canvas (new)
• z-20 — text elements (energy orb, name, description, type strip)
• Tooltip renders outside via AnimatePresence portal

Tailwind does not generate z-15 by default. Either add it to tailwind.config or use style={{ zIndex: 15 }} inline (already shown above).

Gate: Cards render correctly at all sizes. Shader canvas is visible on uncommon/rare/legendary. No z-fighting between shader layer and frame image. TypeScript clean.