build_hooks library

Build-hook helpers for flutter_scene.

Call these from your app's hook/build.dart at build time. buildScenes converts glTF (.glb) and authored .fscene sources into flutter_scene's .fsceneb package format, buildMaterials compiles .fmat custom-material files into a Flutter GPU shader bundle plus a parameter sidecar, buildTextures cooks loose images into the engine's compressed .fstex container, and buildTargetShaderBundleJson compiles raw shader manifests without unused platform backends. buildEngineAssets is optional, putting the shaders flutter_scene itself needs in this app's generated assets rather than in flutter_scene's own.

Everything lands in the app's flutter_scene_generated/ directory and is loaded by source path through loadScene/loadFmatMaterial/loadTexture. dart run flutter_scene:init writes this hook and the one pubspec entry the directory needs.

import 'package:hooks/hooks.dart';
import 'package:flutter_scene/build_hooks.dart';

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

Enums

MaterialAssetMode

Controls where buildMaterials puts generated .fmat shader assets.

SceneAssetMode

Controls where buildScenes puts generated .fsceneb assets.

TargetShaderBundleAssetMode

Controls where a target-specific shader bundle is published.

TextureAssetMode

Controls where buildTextures puts generated .fstex assets.

TextureContent

What a texture's pixels represent, which controls how mip levels are downsampled so the result is correct (color must average in linear light, normals must be averaged as vectors and renormalized).

Functions

buildEngineAssets({required BuildInput buildInput, required BuildOutputBuilder buildOutput}) → Future<void>

Builds the engine's shaders into the app's generated tree, from the app's hook/build.dart (which dart run flutter_scene:init writes for you).

buildMaterials({required BuildInput buildInput, required BuildOutputBuilder buildOutput, List<String>? materials, String bundleName = 'materials', String discoveryRoot = 'assets/', MaterialAssetMode assetMode = MaterialAssetMode.generatedTree}) → Future<void>

Compiles .fmat custom-material files into a Flutter GPU shader bundle plus a parameter-metadata sidecar, for use with ShaderMaterial / PreprocessedMaterial at runtime.

buildScenes({required BuildInput buildInput, required BuildOutputBuilder buildOutput, List<String>? inputFilePaths, String discoveryRoot = 'assets/', SceneAssetMode assetMode = SceneAssetMode.generatedTree, bool compressTextures = false, bool alignForCompression = false}) → void

Converts scene assets so an app loads them by source path with loadScene without hand-editing the asset manifest. Discovers three source kinds under discoveryRoot: .glb (converted to .fsceneb), authored .fscene (compiled to .fsceneb, with referenced images embedded and prefab instances intact for runtime compose), and already-built .fsceneb (an editor's imported/ assets, copied in as-is).

buildTargetShaderBundleJson({required BuildInput buildInput, required BuildOutputBuilder buildOutput, required String manifestFileName, List<Uri> includeDirectories = const [], TargetShaderBundleAssetMode assetMode = TargetShaderBundleAssetMode.generatedTree, String? dataAssetName, int? glesLanguageVersion, bool copyToGeneratedTree = true, bool pruneGeneratedTree = true, String? owner, String? stamp, String? fileVariant}) → Future<void>

Builds a shader bundle and removes backends the target cannot use.

buildTextures({required BuildInput buildInput, required BuildOutputBuilder buildOutput, required List<String> textures, Map<String, TextureContent> contents = const {}, TextureAssetMode assetMode = TextureAssetMode.generatedTree, bool alignForCompression = false}) → void

Cooks loose image assets into the engine's compressed texture container and registers them so an app loads them by source path with loadTexture.