Lay a shader over a camera's whole picture (#299)

A shader so far worked only on its own wearer. Effects over the whole
game picture, such as a vignette, grey, scanlines or a red flash on a
hit, had no place to live. A camera now wears one, drawn the way a
field shader of a particle source is (#170).

- The camera gets a Shader row and, while one is picked, a Shader
  resolution row. The shader's properties follow as camera rows. They
  load, animate and appear in a Properties node under Type Camera.
- Every view keeps masks and objects in one container. CameraShade
  renders it into the camera's picture, cleared to the background,
  and draws the shader over the frame. Game tab and play.html take
  the container off the stage while the picture stands in for it.
- Screen pixels gives the picture as many pixels as it covers on
  screen. Camera pixels uses View width x View height and scales up
  without smoothing.
- A pixel counts as a camera pixel in both (the user's choice). The
  uniform uPixelScale makes Texture size read View width x View
  height, so a Blur keeps its reach at any game scale.
- Each camera wears its own shader, overlay cameras included. A red
  flash on the game camera leaves the HUD of an overlay camera alone.
- The scene view's eye has a Shader switch on the Camera row, off by
  default. With it on, the main camera's shader lies over its frame,
  below symbols and gizmos, and the world around it stays drawn.
- New tool tools/perf-camera-shader.mjs measures the cost.

Measured on stein2 (HD 630, Game tab at Fit 1310x679): a camera
shader that hands the picture through stays inside the scene's own
spread of 3 to 5 fps between runs. A Blur of 4 cost 4 to 8 fps.

Tests:
- Gate on melektaus-atx: 227 files, 3497 tests (3487 + 10).
- e2e 63 alone: 11 checks (6 + 5), e2e sum 1725 counted.
- 63e-63i: pass-through is byte-equal and upright at 100%, flat red
  reaches the corners while the overlay keeps its green, Texture
  size reads 640 x 360 in both resolutions at Fit, no shader draws
  as before, and the scene view shows it only with the switch on.
- Counter-checks: a camera left out of the shader wearers fails 1
  unit test. Counting screen pixels fails 63g with #ab6000.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

src/core/model/animation.ts

@@ -386,7 +386,7 @@ export function animatableDefsOf(
   const declared =
     asset.type === 'behavior'
       ? asset.variables
-      : asset.type === 'sprite' || asset.type === 'text'
+      : asset.type === 'sprite' || asset.type === 'text' || asset.type === 'camera'
         ? shaderParamRows(project, shaderOf(bag))
         : [];
   const taken = new Set(own.map((d) => d.key));

src/core/model/sceneVisibility.ts

@@ -5,7 +5,7 @@
  */
 import { hasSceneIcon, type PlaceableAssetType } from './AssetTypes';
 
-export type VisibilityPart = 'symbol' | 'label' | 'shape';
+export type VisibilityPart = 'symbol' | 'label' | 'shape' | 'shader';
 
 export type TypeVisibility = Record<VisibilityPart, boolean>;
 
@@ -29,17 +29,22 @@ export const VISIBILITY_TYPES: readonly PlaceableAssetType[] = [
 /**
  * The switches a type has. Only a type with a symbol can hide it, every type can show its name,
  * and only what collides has an outline to hide: a collider its shape, a tilemap the outline of
- * its solid cells – the map's art stays. A sprite without its picture would be nothing at all.
+ * its solid cells – the map's art stays. A sprite without its picture would be nothing at all. Only
+ * a camera has a shader to lay over its frame (#299).
  */
 export function visibilityParts(type: PlaceableAssetType): VisibilityPart[] {
   const parts: VisibilityPart[] = hasSceneIcon(type) ? ['symbol', 'label'] : ['label'];
   if (type === 'collider' || type === 'tilemap' || type === 'clip') parts.push('shape');
+  if (type === 'camera') parts.push('shader');
   return parts;
 }
 
-/** What a type shows until it is switched: all of it, except a name nothing showed before. */
+/**
+ * What a type shows until it is switched: all of it, except a name nothing showed before and a
+ * camera's shader.
+ */
 function defaultVisibility(type: PlaceableAssetType): TypeVisibility {
-  return { symbol: true, label: hasSceneIcon(type), shape: true };
+  return { symbol: true, label: hasSceneIcon(type), shape: true, shader: false };
 }
 
 export function defaultSceneVisibility(): SceneVisibility {

src/core/properties/PropertySchema.ts

@@ -102,6 +102,7 @@ import {
   TIME_SCALE_KEY,
 } from './particles';
 import { SHADER_KEY, shaderOf, shaderParamDefs } from './shaders';
+import { SHADER_RESOLUTION_KEY, SHADER_RESOLUTION_OPTIONS } from './cameraShader';
 import { LOOP_KEY as SOUND_LOOP_KEY, VOLUME_KEY as SOUND_VOLUME_KEY } from './sounds';
 import { Theme } from '../../ui';
 
@@ -454,6 +455,16 @@ const ASSET_SCHEMAS: Record<AssetType, PropertySchema> = {
     { key: SEES_KEY, label: 'Sees', kind: 'layers', default: ALL_LAYERS, renderLayers: true },
     // Off: a candidate for the main camera (#5). On: drawn over the main one, see-through (#302).
     { key: OVERLAY_KEY, label: 'Overlay', kind: 'boolean', default: false },
+    // Laid over the camera's whole picture (#299); its parameters follow, as on a sprite.
+    { key: SHADER_KEY, label: 'Shader', kind: 'asset', default: '', assetTypes: ['shader'] },
+    {
+      key: SHADER_RESOLUTION_KEY,
+      label: 'Shader resolution',
+      kind: 'enum',
+      default: 'screen',
+      options: SHADER_RESOLUTION_OPTIONS,
+      shownWhenSet: SHADER_KEY,
+    },
   ],
   sprite: [
     { key: 'width', label: 'Width', kind: 'number', default: 100, min: 1, step: 1 },
@@ -982,10 +993,10 @@ function schemaForBag(project: Project, asset: Asset, bag: PropertyBag): Propert
       shaderParamRows(project, shaderOf(bag)),
       shaderParamRows(project, fieldShaderOf(bag)),
     );
-  if (asset.type === 'text')
+  if (asset.type === 'text' || asset.type === 'camera')
     return [
-      ...FULL_SCHEMAS.text,
-      ...rowsNotClaimedBy(shaderParamRows(project, shaderOf(bag)), FULL_SCHEMAS.text),
+      ...FULL_SCHEMAS[asset.type],
+      ...rowsNotClaimedBy(shaderParamRows(project, shaderOf(bag)), FULL_SCHEMAS[asset.type]),
     ];
   return FULL_SCHEMAS[asset.type];
 }

src/core/properties/cameraShader.ts

@@ -0,0 +1,18 @@
+import { type PropertyBag, textOf } from '../model/Properties';
+
+/**
+ * How many pixels a camera's shader draws its picture with (#299): as many as the picture covers on
+ * screen, sharp at any game scale, or the camera's own raster, scaled up blocky for pixel art.
+ */
+export const SHADER_RESOLUTION_KEY = 'shaderResolution';
+
+export type ShaderResolution = 'screen' | 'camera';
+
+export const SHADER_RESOLUTION_OPTIONS: { value: ShaderResolution; label: string }[] = [
+  { value: 'screen', label: 'Screen pixels' },
+  { value: 'camera', label: 'Camera pixels' },
+];
+
+export function shaderResolutionOf(props: PropertyBag): ShaderResolution {
+  return textOf(props[SHADER_RESOLUTION_KEY] ?? '') === 'camera' ? 'camera' : 'screen';
+}

src/core/store/serialize.ts

@@ -116,11 +116,12 @@ export function deserializeProject(raw: unknown, fallbackId = ''): Project {
   const shaderGraphs = new Map<string, Graph>();
   const shaderRows = new Map<string, PropertyDef[]>();
   const particleGraphs = new Map<string, Graph>();
-  const wearers = new Map<string, 'sprite' | 'particles' | 'text'>();
+  const wearers = new Map<string, 'sprite' | 'particles' | 'text' | 'camera'>();
   for (const a of rawAssets) {
     if (typeof a.id !== 'string' || !a.id || !isAssetType(a.type)) continue;
     rawProps.set(a.id, asRecord(a.props));
-    if (a.type === 'sprite' || a.type === 'particles' || a.type === 'text') wearers.set(a.id, a.type);
+    if (a.type === 'sprite' || a.type === 'particles' || a.type === 'text' || a.type === 'camera')
+      wearers.set(a.id, a.type);
     if (a.type === 'behavior' || a.type === 'variables' || a.type === 'struct') {
       const vars = normalizeVariables(a.variables);
       variables.set(a.id, vars);
@@ -143,8 +144,9 @@ export function deserializeProject(raw: unknown, fallbackId = ''): Project {
     }
   }
   /**
-   * A sprite's, source's or text's rows end with the parameters of the shader its bag names – an
-   * override's, else the asset's. Only a sprite's rows yield to none: a name the others have stays theirs.
+   * A sprite's, source's, text's or camera's rows end with the parameters of the shader its bag names –
+   * an override's, else the asset's. Only a sprite's rows yield to none: a name the others have stays
+   * theirs.
    */
   const schemaOf = (assetId: string, bag: Record<string, unknown>): PropertySchema | undefined => {
     const schema = schemas.get(assetId);