
# All properties

Every property `spring_boot_starter_flutter_scene` reads, under `spring.flutter.scene`. Most are read when the app starts; `enabled` and `debug.enabled` are also read by `spring_core_dart_generator` at build time, which decides by them what code the app contains.

## Why

How many frames a scene draws, whether it moves, when the engine starts and which models there are differ per platform and per build. So they are configuration, not code: a profile file changes them for Android, for the web or for a debug run. This page lists them in one place. The starter's metadata describes the same keys for editors.

## Example

```yaml
# lib/resources/application.yml
spring:
  flutter:
    scene:
      enabled: true          # false: no scene bean, placeholders, no code of the module
      render: animated       # animated | still | off
      max-frame-rate: 30     # the ceiling of every scene; 0: the screen's (60, 120, 144)
      pixel-ratio: 1.5       # the scenes' own; not set: the device's
      canvas: page           # in a browser: page | layer | engine
      light-clustering: true # false: each mesh shades the lamps that reach it
      when:
        touch: still         # a touch screen: one frame that stands
        slow: still          # too slow on this device
      slow:
        frame-time: 16ms     # a beat of the scenes over half of it is slow
        probe: 24            # frames measured before the scenes show
        after: 3s            # slow beats, on end, after they showed
      pause-off-screen: true
      preload: lazy          # eager: the engine starts with the splash
      engine-log: true       # the engine's messages in the app's log
      models:
        hero:
          source: asset:assets/models/hero.glb
          preload: eager     # not set: as `preload` above
      materials:
        glass:
          source: assets/materials/glass.fmat
          preload: eager     # not set: as `preload` above
      app:
        enabled: false       # true: the application's scene
        placement: background  # background | none
        camera:
          position: 0, 1.5, -4
          target: 0, 1, 0
          fov: 45
      debug:
        enabled: true        # the scenes' tab; not set: debug and profile builds
```

```properties
# lib/resources/application.properties: the same
spring.flutter.scene.enabled=true
spring.flutter.scene.render=animated
spring.flutter.scene.max-frame-rate=30
spring.flutter.scene.pixel-ratio=1.5
spring.flutter.scene.canvas=page
spring.flutter.scene.light-clustering=true
spring.flutter.scene.when.touch=still
spring.flutter.scene.when.slow=still
spring.flutter.scene.slow.frame-time=16ms
spring.flutter.scene.slow.probe=24
spring.flutter.scene.slow.after=3s
spring.flutter.scene.pause-off-screen=true
spring.flutter.scene.preload=lazy
spring.flutter.scene.engine-log=true
spring.flutter.scene.models.hero.source=asset:assets/models/hero.glb
spring.flutter.scene.models.hero.preload=eager
spring.flutter.scene.materials.glass.source=assets/materials/glass.fmat
spring.flutter.scene.materials.glass.preload=eager
spring.flutter.scene.app.enabled=false
spring.flutter.scene.app.placement=background
spring.flutter.scene.app.camera.position=0,1.5,-4
spring.flutter.scene.app.camera.target=0,1,0
spring.flutter.scene.app.camera.fov=45
spring.flutter.scene.debug.enabled=true
```

A value for one platform goes into its profile file, as everywhere: `render: still` in `application-android.yml`, or in the profile a debug run uses, where a frame costs several times a release's.

## spring.flutter.scene

| Key | Type | Default | Read | Meaning | Page |
|---|---|---|---|---|---|
| `spring.flutter.scene.enabled` | bool | `true` | by the generator and at the start | Whether the app has scenes. With `false` no scene bean exists, the engine never starts and every scene widget shows its placeholder | [Where scenes do not draw](without-scenes.md) |
| `spring.flutter.scene.render` | `animated`, `still`, `off` | `animated` | at the start | How the scenes draw: up to `max-frame-rate` frames a second, one frame that stands (drawn again only when what it shows changes), or not at all (the widgets show their placeholders) | [Scenes as widgets](scenes.md) |
| `spring.flutter.scene.max-frame-rate` | number | `30` | at the start | The most frames a second a scene draws; a widget may ask for fewer. `0`: as many as the screen shows (in a browser every frame of it, 60, 120 or 144 by the monitor; elsewhere the display's refresh rate, 60 when the system gives none) | [Speed on phones](speed.md#the-ceiling-on-frames) |
| `spring.flutter.scene.pixel-ratio` | number | the device's | at the start | The scenes' own pixel ratio, under the device's: `1` on a screen of `3` draws a ninth of the pixels | [What a scene costs](cost.md) |
| `spring.flutter.scene.canvas` | `page`, `layer`, `engine` | `page` | at the start; `engine` when the engine starts | Which canvas the scenes are on in a browser: `page` (Flutter draws each frame of a scene into the page, and the page again around it), `layer` (a canvas of each scene's own under the page, its frames handed over by the browser, which copies them in Firefox and WebKit) or `engine` (the engine's own canvas under the page, every scene drawn on it where it stands, nothing handed over or copied). A view may ask for `layer` or `page` (`SpringSceneView.canvas`); `engine` is the whole app's. Elsewhere than in a browser Flutter draws the scenes | [Speed on phones](speed.md#the-canvas-in-a-browser) |
| `spring.flutter.scene.light-clustering` | bool | `true` | at the start; applied to the scene of every view | Whether the scenes' lamps (point, spot and area lights) are shaded through the engine's clustering (`Scene.punctualLightClustering`). `false`: every mesh shades the lamps that reach it, cheaper with a few lamps; the clustering makes its lamp textures anew whenever a lamp comes into the view or leaves it, a frame of about 30 ms on an iPhone | [Speed on phones](speed.md#the-lamps-clustering) |
| `spring.flutter.scene.pause-off-screen` | bool | `true` | at the start | Whether a scene scrolled off the screen stops drawing | [Scenes as widgets](scenes.md) |
| `spring.flutter.scene.preload` | `eager`, `lazy` | `lazy` | at the start | When the engine starts: `eager` with the splash, `lazy` when the first scene shows. A model has its own | [The start](start.md) |
| `spring.flutter.scene.engine-log` | bool | `true` | at the start | Whether the engine's own messages (it writes them with Flutter's `debugPrint`) are records of the application's log, under the logger `flutter_scene`: with a time and a level, set by `logging.level.flutter_scene` | [The engine's log](engine-log.md) |

## spring.flutter.scene.when

| Key | Type | Default | Read | Meaning |
|---|---|---|---|---|
| `spring.flutter.scene.when.<condition>` | `still`, `off` | none | at the start | The mode every scene takes while the condition holds: one frame that stands, or the placeholders. The least of `render` and the modes of the conditions that hold wins. The starter's conditions are `touch` (the device's main pointer is a finger: a coarse pointer in a browser, Android and iOS elsewhere) and `slow` (below); an app's own is a `SceneCondition` bean, named by its `name`. A condition not named here changes nothing, and `slow` measures nothing |

While a condition named here is still finding out (`SceneCondition.settled` is `false`), every moving scene waits behind its placeholder. See [Speed on phones](speed.md#drawing-less-where-it-costs-too-much).

## spring.flutter.scene.slow

For the condition `slow` of `spring.flutter.scene.when`. It is decided by the scenes' own frames while the first ones load, their placeholders showing, so they show in the mode they keep; a scene is never switched off in front of the user.

| Key | Type | Default | Read | Meaning |
|---|---|---|---|---|
| `spring.flutter.scene.slow.frame-time` | duration | `16ms` | at the start | The time of a frame: a beat of the scenes (what drawing every moving scene once cost the page's thread, the middle one of those measured) taking more than half of it is slow |
| `spring.flutter.scene.slow.probe` | number | `24` | at the start | How many frames of the first scenes are measured before they show, after the first 6, on which the engine builds its programs |
| `spring.flutter.scene.slow.after` | duration | `3s` | at the start | How long beats are slow, on end, after the scenes showed, before the condition holds: at the next moment no scene moves, and then for the rest of the run. Only frames Flutter does not draw count here (`canvas: layer` or `engine` in a browser) |

See [slow](speed.md#slow).

## spring.flutter.scene.models

| Key | Type | Default | Read | Meaning |
|---|---|---|---|---|
| `spring.flutter.scene.models.<name>.source` | asset or address | none; required | at the start | Where the model's `.glb` file is: an asset of the app (`asset:assets/models/hero.glb`, listed under `flutter: assets:`) or an address (`https://cdn.example.com/hero.glb`; in a browser its server must allow the page's origin). Not a file of `lib/resources/` |
| `spring.flutter.scene.models.<name>.preload` | `eager`, `lazy` | as `spring.flutter.scene.preload` | at the start | When it is loaded: `eager` with the splash, `lazy` when a scene first shows it |

See [Models](models.md).

## spring.flutter.scene.materials

| Key | Type | Default | Read | Meaning |
|---|---|---|---|---|
| `spring.flutter.scene.materials.<name>.source` | path | none; required | at the start, and by the build hook | The material's `.fmat` file, by its path from the app's root (`assets/materials/glass.fmat`), without `asset:`. The build fails when it is not among the files the hook compiled |
| `spring.flutter.scene.materials.<name>.preload` | `eager`, `lazy` | as `spring.flutter.scene.preload` | at the start | When it is loaded: `eager` with the splash, `lazy` when a scene first shows it |

See [Materials](materials.md).

## spring.flutter.scene.app

| Key | Type | Default | Read | Meaning |
|---|---|---|---|---|
| `spring.flutter.scene.app.enabled` | bool | `false` | at the start | Whether the app has one scene of its own (the `applicationScene` bean), made with the splash |
| `spring.flutter.scene.app.placement` | `background`, `none` | `background` | at the start | Where it shows: `background` under every screen, `none` only where the app puts a `SpringSceneView` |
| `spring.flutter.scene.app.camera.position` | `x, y, z` | `0, 0, -5` | at the start | Where the camera is |
| `spring.flutter.scene.app.camera.target` | `x, y, z` | `0, 0, 0` | at the start | What it looks at |
| `spring.flutter.scene.app.camera.fov` | degrees | `45` | at the start | Its vertical field of view |

See [The application's scene](application-scene.md).

## spring.flutter.scene.debug

| Key | Type | Default | Read | Meaning |
|---|---|---|---|---|
| `spring.flutter.scene.debug.enabled` | `true`, `false` | not set | by the generator and at the start | Whether the app has the scenes' tab of the debug panel: `true` in every build, `false` in none (the build leaves its code out), not set in debug and profile builds only |

See [The debug tab](debug-tab.md).

## Keys of other starters the scenes follow

| Key | Starter | Meaning |
|---|---|---|
| `spring.flutter.debug.enabled` | Flutter | Whether the build has the debug panel the scenes' tab is in (see [The debug panel](../spring-boot-starter-flutter/debug-panel.md)) |
| `spring.flutter.frame-meter.enabled` | Flutter | The frame meter, which shows the scenes' frames that Flutter does not draw on a line of their own, `3D 60 fps · 0.9 ms` (see [The frame meter](../spring-boot-starter-flutter/frame-meter.md)) |
| `spring.flutter.splash.tasks.*` | Flutter | How long the splash waits for its tasks, the scenes' among them (see [Splash tasks](../spring-boot-starter-flutter/splash.md#splash-tasks)) |
| `spring.remote.allow-insecure` | Spring Boot | Allows an `http://` address for a model's file; without it only `https://` is read (see [Models](models.md)) |
| `spring.flutter.web.dev-server.headers.<Name>` | Flutter | The headers of `flutter run`, for a cross-origin isolated page (see [What a scene costs](cost.md)) |

## See also

- [Overview](index.md)
- [Speed on phones](speed.md)
- [All properties of spring_boot_starter_flutter](../spring-boot-starter-flutter/properties.md)
- [Properties the build reads](../spring-core-dart-generator/build-properties.md)
- [Modules left out of the build](../spring-core-dart-generator/optimizations/build-conditions.md)
