
# The engine's shaders

`flutter_scene` compiles every shader of its bundle before the first frame: 88 shaders, the lit materials and every effect among them. In a browser that holds the page for 0.3 to 0.7 seconds, and over 3 seconds on a first visit. An app whose scenes draw with a few of them builds a bundle of those alone, in a hook of its own.

## Why

The start of the engine is a step a user waits for, with the splash or with a placeholder. It compiles every shader of the engine, also those the app never draws with. A bundle in the app's own tree takes the place of the engine's: the engine reads the app's tree first, and a package's copy never wins. So the bundle is built by the app, not by the starter: Dart runs a build hook for one package and lets it write into that package alone, and only the app knows what its scenes draw with. The starter has the function; the app's hook is the call.

## Example

```dart
// hook/build.dart of the app
import 'package:hooks/hooks.dart';
import 'package:spring_boot_starter_flutter_scene/build_hooks.dart';

void main(List<String> args) async {
  await build(args, (input, output) async {
    await buildSceneAssets(buildInput: input, buildOutput: output);
  });
}
```

```yaml
# pubspec.yaml of the app
dependencies:
  hooks: ^2.0.0
flutter:
  assets:
    - lib/spring_gen/flutter_scene_generated/
    - path: lib/spring_gen/flutter_scene_generated/opengl_es/
      platforms: [web]
```

## buildSceneAssets

One call makes everything of the app's scenes that is made at build time.

| Parameter | Type | Default | Meaning |
|---|---|---|---|
| `buildInput` | `BuildInput` | required | The hook's input |
| `buildOutput` | `BuildOutputBuilder` | required | The hook's output |
| `shaders` | `Set<String>?` | `unlitSceneShaders` | The names of the engine's shaders the bundle has; `null`: no bundle of the app's, the engine's whole one is used |
| `materials` | `bool` | `true` | Compiles the `.fmat` materials under `sources`, and fails when a material of `spring.flutter.scene.materials` is not among them (see [Materials](materials.md)) |
| `models` | `bool` | `true` | Converts the `.glb` and `.fscene` files under `sources`, loadable by the path of their source |
| `sources` | `String` | `assets/` | The app's folder the materials and models are in |

`buildSceneShaders` is the bundle alone: the same call with `materials` and `models` off.

It is in a library of its own, `package:spring_boot_starter_flutter_scene/build_hooks.dart`: it runs on the Dart VM only (it reads files and runs the SDK's shader compiler), so it is not part of the starter's main library.

## The list

The default list (`unlitSceneShaders`, six shaders) is for scenes of unlit and custom unlit (`.fmat`) materials:

| Shader |
|---|
| `UnskinnedVertex` |
| `UnlitFragment` |
| `FullscreenVertex` |
| `ResolveFragment` |
| `CopyFragment` |
| `PrefilterRadianceCubeFragment` |

A scene with lit materials (a `.glb` model has them) names what it needs:

```dart
await buildSceneAssets(
  buildInput: input,
  buildOutput: output,
  shaders: {...unlitSceneShaders, 'StandardFragment'},
);
```

Or it keeps the engine's whole bundle by having no hook: without the hook everything works.

- A name the engine does not have fails the build, naming the shaders it has.
- A shader missing from the bundle fails at draw time with no name in the error: look at every scene after changing the list.

## The generated assets

What the hook makes goes into `lib/spring_gen/flutter_scene_generated/`, with the rest of the generated code, as `pubspec.yaml` lists it above. The app's root gets no folder for it.

`flutter_scene`'s own hooks write into a folder at the root of the app and cannot be told another place. So the starter runs them for a stand-in of the app under `.dart_tool/spring_scene/` and copies their output over. At run time the engine finds its assets by the end of their address, wherever the folder is.

Generated assets are bound to the Flutter that compiled them, so what is in the folder is never committed: the two `.gitignore` files the build writes there ignore everything else in it. The files themselves are committed. They keep the folders in git, so the asset entries name folders that exist before the first build. An app that ignores `spring_gen/` as a whole keeps this one folder:

```
**/spring_gen/*
!**/spring_gen/flutter_scene_generated/
```

A `pubspec.yaml` without the entry stops the build with the lines to add.

## See also

- [The start in events and words](start.md): the engine's start as an event, with the time it took
- [What a scene costs](cost.md)
- [The debug tab](debug-tab.md): the time of the engine's start
