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 (or standard ETC1S .ktx2, see TextureEncoding), 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);
  });
}

Classes

TextureEncoding Assets and loading
How buildTextures stores a cooked texture.

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 Assets and loading
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 {}, TextureEncoding encoding = TextureEncoding.universal, Map<String, TextureEncoding> encodings = 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.