---
name: flutter_scene-looks
version: 4
description: Give a flutter_scene render a deliberate, polished look. Use this whenever a scene looks flat, dull, or washed out, or whenever the ask is to make it look good, because a good look is lighting plus post-processing, not geometry. Ships copy-paste EnvironmentSettings presets that configure the whole stack coherently.
---

# Making flutter_scene look good

The single most common reason a flutter_scene render looks amateur is that the post-processing stack was left at defaults. flutter_scene has a deep lit-and-post pipeline (image-based lighting, tone mapping, bloom, lens flares, ambient occlusion, screen-space reflections, fog, god rays, depth of field, color grading, vignette, film grain). Out of the box almost all of it is off, so a bare scene is technically correct and visually flat.

**The insight: a polished look is lighting and post-processing, not geometry.** Better meshes will not fix a flat render. Do not spend effort on modeling detail when the scene reads dull; spend it on the look. And a look is a *coherent* set of choices, not twelve knobs turned independently. Turning bloom, AO, SSR, fog, grain, and grading up one at a time, each by feel, lands in muddy incoherent territory. Pick one deliberate preset and paste it whole.

## Apply a look in one line

Every scene-wide look field lives on one aggregate value, `EnvironmentSettings`, assigned through a single setter:

```dart
scene.environmentSettings = EnvironmentSettings(/* fields below */);
```

That one assignment configures tone mapping, exposure, image-based-lighting intensity, and the entire post stack, **including** fog, god rays, depth of field, and auto exposure. You do not need to touch `scene.fog`, `scene.godRays`, `scene.depthOfField`, or `scene.autoExposure` separately; those are the live per-effect objects, but `EnvironmentSettings` carries all of their fields and applies them for you. Every effect is off by default, so a preset only names the fields it turns on.

`EnvironmentSettings` is also a blendable snapshot. Read the current look with `scene.environmentSettings`, and cross-fade two looks with `EnvironmentSettings.lerp(a, b, t)` driven from an animation. That is how you transition day to night or ramp an effect in.

## Lights are separate, and still matter

`EnvironmentSettings` covers image-based lighting (the `environment` map) and the whole post stack, but **direct lights are not part of it.** Shadows, god rays, and any strong key light come from the scene's lights, set separately:

```dart
scene.directionalLight = DirectionalLight(
  direction: vm.Vector3(-0.4, -1.0, -0.3),
  intensity: 4.0,
  castsShadow: true,        // shadows are off until you ask
);
```

An unset `scene.environment` still resolves to a default studio IBL, so a `PhysicallyBasedMaterial` is always lit. But a scene with no direct light is soft and shadowless. God rays require a shadow-casting `DirectionalLight`; shadows require `castsShadow: true` on the light.

## The four looks

Paste one whole. Each is a real `EnvironmentSettings` literal; import `package:vector_math/vector_math.dart as vm` for the `Vector3` color fields. AO, SSR, god rays, and depth of field require a `PerspectiveCamera` (the only built-in camera).

### showcase

Clean, bright product-viz beauty. Punchy tone mapping, soft bloom on highlights, grounded contact occlusion, and real reflections. The default reach-for-it look.

```dart
scene.environmentSettings = EnvironmentSettings(
  toneMapping: ToneMappingMode.aces,
  exposure: 1.0,
  bloomEnabled: true,
  bloomThreshold: 1.1,
  bloomIntensity: 0.2,
  bloomScatter: 0.7,
  ambientOcclusionEnabled: true,
  ambientOcclusionMethod: AmbientOcclusionMethod.groundTruth,
  ambientOcclusionBentNormals: true,
  ambientOcclusionSpecularMode: SpecularAmbientOcclusionMode.bentCone,
  ambientOcclusionIntensity: 1.0,
  screenSpaceReflectionsEnabled: true,
  screenSpaceReflectionsIntensity: 1.0,
  vignetteEnabled: true,
  vignetteIntensity: 0.25,
);
```

### stylized

Vivid and graphic. Saturated, slightly warm, glowing, flatter shading (no heavy occlusion or reflections). For playful or illustrative scenes.

```dart
scene.environmentSettings = EnvironmentSettings(
  toneMapping: ToneMappingMode.aces,
  colorGradingEnabled: true,
  saturation: 1.25,
  contrast: 1.1,
  brightness: 1.05,
  temperature: 0.1,
  bloomEnabled: true,
  bloomThreshold: 0.9,
  bloomIntensity: 0.28,
  bloomScatter: 0.8,
  vignetteEnabled: true,
  vignetteIntensity: 0.2,
);
```

### moody

Dark, cinematic, atmospheric. Lower exposure, cool graded, foggy, heavy vignette, subtle grain and aberration, deep occlusion. God rays if the scene has a shadow-casting sun. Use a cool horizon-colored fog.

```dart
scene.environmentSettings = EnvironmentSettings(
  toneMapping: ToneMappingMode.aces,
  exposure: 0.8,
  colorGradingEnabled: true,
  contrast: 1.15,
  saturation: 0.9,
  temperature: -0.1,
  fogEnabled: true,
  fogMode: FogMode.exponential,
  fogColor: vm.Vector3(0.05, 0.06, 0.09),
  fogDensity: 0.03,
  ambientOcclusionEnabled: true,
  ambientOcclusionMethod: AmbientOcclusionMethod.groundTruth,
  ambientOcclusionIntensity: 1.2,
  ambientOcclusionPower: 1.8,
  vignetteEnabled: true,
  vignetteIntensity: 0.6,
  vignetteRadius: 0.6,
  filmGrainEnabled: true,
  filmGrainIntensity: 0.25,
  chromaticAberrationEnabled: true,
  chromaticAberrationIntensity: 0.15,
  godRaysEnabled: true,          // needs scene.directionalLight with castsShadow: true
  godRaysIntensity: 1.0,
  godRaysDensity: 0.6,
  godRaysColor: vm.Vector3(1.0, 0.95, 0.85),
);
```

### clean

Neutral and honest. Minimal post, no grading, no bloom, no vignette, just correct tone mapping and gentle grounding occlusion. The right look for an editor, an inspector, a UI-embedded viewer, or anywhere you want an accurate read of the actual material.

```dart
scene.environmentSettings = EnvironmentSettings(
  toneMapping: ToneMappingMode.pbrNeutral,   // the engine default
  exposure: 1.0,
  ambientOcclusionEnabled: true,
  ambientOcclusionIntensity: 0.8,
  ambientOcclusionHalfResolution: true,
);
```

## Tuning from a preset

Start from the nearest look, then move one field at a time.

- **Too dim or too bright overall.** Change `exposure` (default 1.0), not per-light intensity. Or turn on `autoExposureEnabled: true` to let the scene meter itself.
- **Highlights not glowing.** Lower `bloomThreshold` toward 1.0 or below, or raise `bloomIntensity`. `bloomScatter` widens the glow.
- **Want a lens flare off a bright source.** Turn on `lensFlareEnabled` (needs `bloomEnabled`). Keep `lensFlareIntensity` modest and drop `lensFlareHaloIntensity` first if the flare washes the frame; the halo is the broad wash, the ghosts are the crisp chain.
- **Reads flat and ungrounded.** `ambientOcclusionEnabled: true`. Use `AmbientOcclusionMethod.groundTruth` for quality, keep `ambientOcclusionHalfResolution: true` for cost.
- **Colors feel wrong.** Turn on `colorGradingEnabled` and reach for `saturation`, `contrast`, `temperature`, `tint` before anything else.
- **Wrong tone-map feel.** `ToneMappingMode.aces` is contrasty and filmic, `pbrNeutral` (default) preserves hue and saturation, `agx` is the most neutral highlight rolloff. Do not reintroduce an `exposure: 2.0` hack; that was an artifact of an older renderer.

## Micro-surface metrics and anti-waxiness tuning

When tuning procedural materials or custom shaders, use surface metrics and exposure discipline to eliminate waxiness, plastic reads, or harsh aliasing:

- **Surface reads like smooth plastic.** Increase high-frequency micro-scale variation. Low 1-pixel luminance gradients `(|dL/dx| + |dL/dy|) / 2` indicate untextured or overly smooth surfaces.
- **Blotchy macro clouds.** Balance high-frequency and low-frequency energy ratios (`hf/lf`). High variance with low fine detail indicates large-scale noise patches without adequate surface grain.
- **Harsh normal-map glitter or torn noise.** Check terminator crossing behavior under low grazing light angles (sun low on the horizon). Over-amplified normal maps flip adjacent pixels between full light and full shadow.
- **Colors look washed out in bright areas.** Tone mapping curves compress channel differences near the shoulder. A surface reading high brightness with low saturation is often over-exposed rather than under-pigmented; reduce exposure to restore natural material saturation.

## Look tools that are not on EnvironmentSettings

Anti-aliasing, reflection probes, and planar reflectors affect the look but are set outside `EnvironmentSettings`, so a preset does not turn them on.

- **Anti-aliasing** is a `Scene` field. The default `AntiAliasingMode.auto` already picks `msaa` where the backend supports it and `fxaa` otherwise, so edges are handled. Reach for `scene.antiAliasingMode = AntiAliasingMode.smaa` when `fxaa` looks mushy (it blurs texture detail) and `msaa` is unavailable; SMAA keeps edges clean without the blur, at ~3x fxaa cost.
- **Reflection probes** capture true local reflections that SSR cannot, because SSR only reflects what is on screen. Attach a `ReflectionProbeComponent` to a node placed at the reflective spot (a room, a mirror ball); it captures the surroundings into a parallax-corrected box and blends with the environment. The capture renders the scene six times, so it happens once on activate (or on an explicit `requestCapture()`), never per frame.
- **Planar reflectors** render a true per-frame mirror for one flat surface (a mirror, a glossy floor), which neither SSR nor a probe can produce. Attach a `PlanarReflectorComponent` to the mirror node and give the surface a `.fmat` material declaring `engine_inputs: [ planar_reflection ]`; the component renders the scene once more per frame from the reflected camera and the material samples it with `GetPlanarReflection()`. That extra scene render is the cost, so bound it with `resolutionScale` (default 0.5) and `layerMask`. See `references/looks.md` for all three.

## Cost

The post stack is not free. AO, SSR, depth of field, and god rays each add screen-space passes, and mobile and web are the budget. Keep `ambientOcclusionHalfResolution: true`, prefer `DepthOfFieldQuality.low` on mobile, and do not stack SSR plus god rays plus depth of field on a low-end target without profiling. The `clean` look is nearly free; `moody` is the heaviest. See `references/looks.md` for the full per-effect knob reference, defaults, and cost notes.