### Setup and Run Flutter Scene Example

Source: https://github.com/bdero/flutter_scene/blob/master/examples/README.md

Commands to resolve workspace dependencies, enable native assets, and run the Flutter Scene example app with GPU acceleration.

```sh
flutter pub get                              # resolves the workspace
flutter config --enable-native-assets        # one-time setup

cd examples/flutter_app
flutter run --enable-flutter-gpu             # add `-d <device>` as needed
```

--------------------------------

### Complete PBR Material Setup in Flutter Scene

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/04-material.md

Example demonstrating the full setup of a Physically Based Material, including loading textures, creating the material, fine-tuning parameters, and applying it to a mesh.

```dart
import 'package:flutter_scene/scene.dart';
import 'package:flutter_scene/gpu.dart' as gpu;

// Load textures
final colorTex = await gpu.loadGpuTextureFromAsset('assets/color.png');
final normalTex = await gpu.loadGpuTextureFromAsset('assets/normal.png');
final mrTex = await gpu.loadGpuTextureFromAsset('assets/metallic_roughness.png');

// Create material
final material = PhysicallyBasedMaterial(
  baseColorTexture: colorTex,
  normalTexture: normalTex,
  metallicRoughnessTexture: mrTex,
);

// Fine-tune parameters
material.baseColorFactor = Vector4(1, 0.9, 0.8, 1);  // Warm tint
material.normalScale = 1.2;
material.roughnessFactor = 0.6;

// Apply to mesh
final geometry = PlaneGeometry(width: 2, height: 2);
final mesh = Mesh(geometry, material);
node.mesh = mesh;
```

--------------------------------

### Flutter Scene Repository Setup

Source: https://github.com/bdero/flutter_scene/blob/master/packages/flutter_scene/README.md

Commands to set up and run the example app from a cloned repository. Includes package retrieval, native asset enablement, and running the app on different platforms.

```sh
flutter pub get                                             # resolves the workspace
flutter config --enable-native-assets                       # one-time setup
flutter config --enable-dart-data-assets                    # one-time setup for DataAssets-backed .fmat materials

cd examples/flutter_app
flutter create . --platforms=macos,ios,android,linux,windows,web  # generate gitignored platform stubs
flutter run --enable-flutter-gpu --enable-impeller            # native; add `-d <device>` if needed
flutter run -d chrome                                         # web
```

--------------------------------

### Example: Physics-Driven Scene Setup

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/10-physics.md

Sets up a basic 3D scene with a physics world, a static ground, and a dynamic falling box. The physics world is stepped each frame.

```dart
import 'package:flutter_scene/scene.dart';

final scene = Scene();
final physicsWorld = PhysicsWorld();
scene.add(physicsWorld);

// Ground (static)
final groundBody = RigidBody(type: BodyType.static);
final groundCollider = Collider(
  shape: BoxShape(halfExtents: Vector3(10, 0.5, 10)),
);
final groundNode = Node(name: 'ground')
  ..addComponent(groundBody)
  ..addComponent(groundCollider);
scene.add(groundNode);

// Falling box
final boxBody = RigidBody(
  type: BodyType.dynamic,
  mass: 2.0,
);
final boxCollider = Collider(
  shape: BoxShape(halfExtents: Vector3(0.5, 0.5, 0.5)),
  material: PhysicsMaterial(
    staticFriction: 0.5,
    dynamicFriction: 0.3,
    restitution: 0.6,
  ),
);
final boxGeometry = CuboidGeometry(width: 1, height: 1, depth: 1);
final boxMaterial = PhysicallyBasedMaterial();
final boxMesh = Mesh(boxGeometry, boxMaterial);

final boxNode = Node(
  name: 'box',
  localTransform: Matrix4.translationValues(0, 5, 0),
  mesh: boxMesh,
)
  ..addComponent(boxBody)
  ..addComponent(boxCollider);
scene.add(boxNode);

// Step physics each frame
scene.onTick = (elapsed, deltaSeconds) {
  physicsWorld.step(deltaSeconds);
};
```

--------------------------------

### Create Example App Platforms

Source: https://github.com/bdero/flutter_scene/blob/master/README.md

Generates gitignored platform stubs for the example app. Navigate to the example app directory before running.

```sh
cd examples/flutter_app
flutter create . --platforms=macos,ios,android,linux,windows,web
```

--------------------------------

### Quick Start: Scene Setup with Rapier Physics

Source: https://github.com/bdero/flutter_scene/blob/master/packages/flutter_scene_rapier/README.md

Initialize a RapierWorld, add a static floor, and a dynamic falling box to the scene. Physics are advanced on a fixed timestep and transforms are interpolated.

```dart
import 'package:flutter_scene/scene.dart' hide Material; // see note below
import 'package:flutter_scene_rapier/flutter_scene_rapier.dart';
import 'package:vector_math/vector_math.dart';

final scene = Scene();
final world = RapierWorld(gravity: Vector3(0, -9.81, 0));
scene.root.addComponent(world);

// A static floor.
final floor = Node(localTransform: Matrix4.translation(Vector3(0, -0.5, 0)));
floor.addComponent(RapierRigidBody(type: BodyType.fixed));
floor.addComponent(RapierCollider(shape: BoxShape(halfExtents: Vector3(10, 0.5, 10))));
scene.add(floor);

// A falling dynamic box.
final box = Node(localTransform: Matrix4.translation(Vector3(0, 5, 0)));
box.addComponent(RapierRigidBody(type: BodyType.dynamic_, mass: 1));
box.addComponent(RapierCollider(shape: BoxShape(halfExtents: Vector3.all(0.5))));
scene.add(box);

// React to contacts and triggers.
world.collisions.listen((event) {
  // CollisionBegan / CollisionEnded / TriggerEntered / TriggerExited
});
```

--------------------------------

### Installation: Main Executable

Source: https://github.com/bdero/flutter_scene/blob/master/examples/smoke_render/linux/CMakeLists.txt

Installs the main application executable to the root of the bundle directory.

```cmake
install(TARGETS ${BINARY_NAME} RUNTIME DESTINATION "${CMAKE_INSTALL_PREFIX}"
  COMPONENT Runtime)
```

--------------------------------

### Run Example App (Web)

Source: https://github.com/bdero/flutter_scene/blob/master/README.md

Runs the example app on the web, specifically targeting the Chrome browser.

```sh
flutter run -d chrome
```

--------------------------------

### Node Instantiation Example

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/02-node.md

Example of creating a Node with a specific name and translation, then adding it to a scene.

```dart
final node = Node(
  name: 'character',
  localTransform: Matrix4.translationValues(0, 1, 0),
);
scene.add(node);
```

--------------------------------

### Run Example App (Native)

Source: https://github.com/bdero/flutter_scene/blob/master/README.md

Runs the example app on native platforms with GPU and Impeller enabled. Add '-d <device>' if targeting a specific device.

```sh
flutter run --enable-flutter-gpu --enable-impeller
```

--------------------------------

### PhysicalSkySource Example Usage

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/environment.md

Example of how to instantiate and use PhysicalSkySource with custom sun intensity and size. This is typically used within a SkyEnvironment setup.

```dart
final sky = SkyEnvironment(
  source: PhysicalSkySource(
    sunIntensity: 1.5,
    sunSize: 1.0,
  ),
);
```

--------------------------------

### Installation: Define Bundle Directories

Source: https://github.com/bdero/flutter_scene/blob/master/examples/smoke_render/linux/CMakeLists.txt

Sets the installation paths for data and library directories within the application bundle.

```cmake
set(INSTALL_BUNDLE_DATA_DIR "${CMAKE_INSTALL_PREFIX}/data")
set(INSTALL_BUNDLE_LIB_DIR "${CMAKE_INSTALL_PREFIX}/lib")
```

--------------------------------

### SamplerOptions Example

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/gpu-shaders.md

Example of creating a SamplerOptions object with linear filtering and repeat wrap modes for all coordinates.

```dart
final sampler = gpu.SamplerOptions(
  minFilter: gpu.MinMagFilter.linear,
  magFilter: gpu.MinMagFilter.linear,
  mipFilter: gpu.MipFilter.linear,
  uAddress: gpu.SamplerAddressMode.repeat,
  vAddress: gpu.SamplerAddressMode.repeat,
);
```

--------------------------------

### Installation: Bundled Plugin Libraries

Source: https://github.com/bdero/flutter_scene/blob/master/examples/smoke_render/linux/CMakeLists.txt

Installs all bundled plugin libraries to the lib directory within the bundle.

```cmake
foreach(bundled_library ${PLUGIN_BUNDLED_LIBRARIES})
  install(FILES "${bundled_library}"
    DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
    COMPONENT Runtime)
endforeach(bundled_library)
```

--------------------------------

### Installation: Flutter Library

Source: https://github.com/bdero/flutter_scene/blob/master/examples/smoke_render/linux/CMakeLists.txt

Installs the main Flutter library file to the lib directory within the bundle.

```cmake
install(FILES "${FLUTTER_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
  COMPONENT Runtime)
```

--------------------------------

### Example: Create NodeCamera from Node

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/03-camera.md

Shows how to create a NodeCamera instance by providing a node that has a CameraComponent attached.

```dart
final camNode = Node()..addComponent(CameraComponent(PerspectiveProjection()));
final camera = NodeCamera(camNode);
```

--------------------------------

### Flutter Scene Viewer Example

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/03-camera.md

A complete Flutter widget example demonstrating how to set up a Scene, a PerspectiveCamera, add a model node, and render it using a CustomPaint widget.

```dart
import 'package:flutter/material.dart';
import 'package:flutter_scene/scene.dart';
import 'package:vector_math/vector_math.dart' as vm;

class SceneViewerExample extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final scene = Scene();
    final camera = PerspectiveCamera(
      position: vm.Vector3(0, 2, 5),
      target: vm.Vector3.zero(),
    );

    // Load and add a model
    final node = Node(name: 'model');
    scene.add(node);

    return CustomPaint(
      painter: ScenePainter(scene, camera),
      isComplex: true,
    );
  }
}

class ScenePainter extends CustomPainter {
  ScenePainter(this.scene, this.camera);
  
  final Scene scene;
  final Camera camera;

  @override
  void paint(Canvas canvas, Size size) {
    scene.render(canvas, size, camera: camera);
  }

  @override
  bool shouldRepaint(ScenePainter oldDelegate) => false;
}
```

--------------------------------

### Installation: Flutter Assets

Source: https://github.com/bdero/flutter_scene/blob/master/examples/smoke_render/linux/CMakeLists.txt

Removes and then installs the Flutter assets directory to the data directory within the bundle.

```cmake
set(FLUTTER_ASSET_DIR_NAME "flutter_assets")
install(CODE "
  file(REMOVE_RECURSE \"${INSTALL_BUNDLE_DATA_DIR}/${FLUTTER_ASSET_DIR_NAME}\")
  " COMPONENT Runtime)
install(DIRECTORY "${PROJECT_BUILD_DIR}/${FLUTTER_ASSET_DIR_NAME}"
  DESTINATION "${INSTALL_BUNDLE_DATA_DIR}" COMPONENT Runtime)
```

--------------------------------

### Complete IBL Setup with Procedural Sky

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/environment.md

Demonstrates a full Image-Based Lighting (IBL) setup using a procedural sky. This includes loading an environment map, configuring the sky, and applying it to a PBR material.

```dart
import 'package:flutter_scene/scene.dart';

// 1. Load environment map
final customEnv = await EnvironmentMap.fromAsset(
  'assets/environments/studio_light.hdr',
);

// 2. Or use procedural sky with environment
final sky = SkyEnvironment(
  source: PhysicalSkySource(
    sunIntensity: 2.0,
    sunSize: 1.0,
  ),
  appliesEnvironment: true,
);

// 3. Apply environment to scene
// (Via materials, or set as scene default)

// 4. Create PBR material
final material = PhysicallyBasedMaterial(
  baseColorTexture: colorTex,
  metallicRoughnessTexture: mrTex,
  normalTexture: normalTex,
  environment: customEnv,  // Per-material override
)
..metallicFactor = 0.2
..roughnessFactor = 0.5;

// 5. Render
final mesh = Mesh(geometry, material);
node.mesh = mesh;
scene.add(node);
```

--------------------------------

### Installation: AOT Library (Non-Debug)

Source: https://github.com/bdero/flutter_scene/blob/master/examples/smoke_render/linux/CMakeLists.txt

Installs the Ahead-Of-Time (AOT) compilation library to the lib directory, but only for non-Debug builds.

```cmake
if(NOT CMAKE_BUILD_TYPE MATCHES "Debug")
  install(FILES "${AOT_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
    COMPONENT Runtime)
endif()
```

--------------------------------

### Character Idle-to-Run Transition Example

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/06-animation.md

Illustrates how to set up and transition between idle and run animations for a character using weights and crossfading.

```dart
import 'package:flutter_scene/scene.dart';

class CharacterController {
  late Node character;
  late AnimationClip idle;
  late AnimationClip run;
  
  Future<void> init() async {
    character = await Node.fromGlbAsset('assets/character.glb');
    
    // Assume animations are imported with these names
    idle = character.createAnimationClip(
      // Get animation by name from loaded character
    )!
    run = character.createAnimationClip(
      // Get animation by name from loaded character
    )!
    
    idle.weight = 1.0
    idle.looped = true
    run.weight = 0.0
  }
  
  void startRunning() {
    // Crossfade: idle → run over 200ms
    animateTo(run, duration: Duration(milliseconds: 200))
  }
  
  void stopRunning() {
    // Crossfade: run → idle over 150ms
    animateTo(idle, duration: Duration(milliseconds: 150))
  }
  
  void animateTo(AnimationClip target, {required Duration duration}) {
    // Implement linear crossfade
    // (In practice, use a tween framework or custom logic)
  }
}
```

--------------------------------

### Enable Native Assets

Source: https://github.com/bdero/flutter_scene/blob/master/README.md

One-time setup command to enable native assets. Required for certain functionalities.

```sh
flutter config --enable-native-assets
```

--------------------------------

### Installation: Native Assets

Source: https://github.com/bdero/flutter_scene/blob/master/examples/smoke_render/linux/CMakeLists.txt

Installs native assets provided by build.dart to the lib directory within the bundle.

```cmake
set(NATIVE_ASSETS_DIR "${PROJECT_BUILD_DIR}native_assets/linux/")
install(DIRECTORY "${NATIVE_ASSETS_DIR}"
   DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
   COMPONENT Runtime)
```

--------------------------------

### Example: Add, Find, and Remove Components

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/component.md

Demonstrates how to add instances of custom and built-in components to a node, retrieve them using `findComponent` and `findComponents`, and subsequently remove them.

```dart
final node = Node();

// Add components
node.addComponent(MeshComponent(mesh));
node.addComponent(RotatingComponent());

// Find components
final meshComp = node.findComponent<MeshComponent>();
final rotators = node.findComponents<RotatingComponent>();

// Remove
node.removeComponent(meshComp!);
```

--------------------------------

### Example BloomSettings Configuration

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/11-post-processing.md

Apply a bloom effect with specific parameters. This example sets a lower threshold to capture more bright areas and increases intensity for a stronger bloom effect.

```dart
scene.postProcess = PostProcessSettings(
  bloom: BloomSettings(
    threshold: 0.8,   // Brightest 20% of image
    intensity: 2.0,   // Double the bloom
    width: 15.0,
    iterations: 8,
  ),
);
```

--------------------------------

### Screen Point to Ray Example - Camera

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/03-camera.md

An example demonstrating how to use screenPointToRay to cast a ray into the scene and perform a raycast. This is commonly used for object selection or interaction.

```dart
final ray = camera.screenPointToRay(
  Offset(100, 200),  // screen position
  Size(800, 600),    // view size
);
final hit = scene.raycast(ray);
```

--------------------------------

### Example: Attach Camera to Node and Render Scene

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/03-camera.md

Demonstrates attaching a CameraComponent with PerspectiveProjection to a node, setting its transform, and then rendering the scene using a NodeCamera.

```dart
final cameraNode = Node(name: 'camera');
cameraNode.addComponent(CameraComponent(PerspectiveProjection()));
cameraNode.localTransform = Matrix4.translationValues(0, 2, 5);

final nodeCamera = NodeCamera(cameraNode);
scene.render(canvas, size, camera: nodeCamera);
```

--------------------------------

### Installation: Clean Build Bundle Directory

Source: https://github.com/bdero/flutter_scene/blob/master/examples/smoke_render/linux/CMakeLists.txt

Removes the build bundle directory before installation to ensure a clean state.

```cmake
install(CODE "
  file(REMOVE_RECURSE \"${BUILD_BUNDLE_DIR}/\")
  " COMPONENT Runtime)
```

--------------------------------

### Mesh Creation Example

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/05-mesh.md

Demonstrates creating a single-material mesh with PlaneGeometry and a PhysicallyBasedMaterial, and a multi-material mesh with distinct geometry and material for body and windows.

```dart
final geometry = PlaneGeometry(width: 2, height: 2);
final material = PhysicallyBasedMaterial();
final mesh = Mesh(geometry, material);

// Or multi-material:
final mesh = Mesh.primitives(primitives: [
  MeshPrimitive(bodyGeom, bodyMaterial),
  MeshPrimitive(windowsGeom, glassMaterial),
]);
```

--------------------------------

### Custom Shader Material Example

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/gpu-shaders.md

Demonstrates creating a custom ShaderMaterial using a compiled shader bundle and a fragment shader.

```glsl
#version 460

precision highp float;

layout(location = 0) out vec4 fragColor;

uniform sampler2D colorTexture;
uniform sampler2D normalTexture;

void main() {
  // Custom rendering logic
  vec3 color = texture(colorTexture, vec2(0.5)).rgb;
  fragColor = vec4(color, 1.0);
}
```

```dart
final library = await gpu.loadShaderLibraryAsync('my_shader.shaderbundle');
final material = ShaderMaterial(
  fragmentShader: library!['main']!,
);
```

--------------------------------

### Complete Lighting Setup

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/07-lighting.md

Sets up a directional light, an environment map for physically based materials, and renders the scene. Ensure the environment map asset is correctly placed.

```dart
import 'package:flutter_scene/scene.dart';
import 'package:vector_math/vector_math.dart' as vm;

final scene = Scene();

// 1. Set directional light (sun)
final light = DirectionalLight(
  direction: vm.Vector3(-0.3, -1, -0.2),
  color: vm.Vector3(1, 0.95, 0.9),  // Warm white
  intensity: 2.5,
  castsShadow: true,
  shadowSoftness: 0.12,
  shadowCascadeCount: 4,
  shadowMaxDistance: 200,
);
scene.directionalLight = light;

// 2. Set environment map (IBL)
final env = await EnvironmentMap.fromAsset('assets/studio.png');

// 3. Apply to materials
final material = PhysicallyBasedMaterial()
  ..environment = env  // Use custom environment
  ..metallicFactor = 0.2
  ..roughnessFactor = 0.5;

final mesh = Mesh(geometry, material);
node.mesh = mesh;

// 4. Render
scene.render(canvas, size, camera: camera);
```

--------------------------------

### Use Placeholder Texture Example

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/04-material.md

An example demonstrating how to use the `getWhitePlaceholderTexture` static method to provide a fallback texture for the base color.

```dart
final colorTex = material.baseColorTexture ?? 
  Material.getWhitePlaceholderTexture();
```

--------------------------------

### Installation: ICU Data File

Source: https://github.com/bdero/flutter_scene/blob/master/examples/smoke_render/linux/CMakeLists.txt

Installs the ICU data file to the data directory within the bundle.

```cmake
install(FILES "${FLUTTER_ICU_DATA_FILE}" DESTINATION "${INSTALL_BUNDLE_DATA_DIR}"
  COMPONENT Runtime)
```

--------------------------------

### Install Build Hook and Enable Data Assets

Source: https://github.com/bdero/flutter_scene/blob/master/MATERIALS.md

Installs the Flutter Scene build hook and enables Dart Data Assets support for compiling materials.

```sh
dart run flutter_scene:init
flutter config --enable-dart-data-assets
```

--------------------------------

### SkyEnvironment and Skybox Setup

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/07-lighting.md

Shows how to set up a SkyEnvironment for procedural skies or a Skybox using custom shaders or equirectangular textures.

```dart
import 'package:flutter_scene/scene.dart' show 
  SkyEnvironment, SkySource, Skybox;

// Procedural sky
final sky = SkyEnvironment(source: PhysicalSkySource());

// Custom shader sky
final skybox = Skybox(source: ShaderSkySource(shader));

// Equirectangular image
final skybox = Skybox(
  source: EnvironmentSkySource(equirectangularTexture),
);
```

--------------------------------

### Initialize DirectionalLight in Scene

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/07-lighting.md

Example of creating and attaching a DirectionalLight to the scene. Ensure shadow casting is enabled if needed.

```dart
final light = DirectionalLight(
  direction: Vector3(-0.3, -1, -0.2),  // From upper left
  color: Vector3(1, 1, 1),             // White
  intensity: 3.0,
  castsShadow: true,
  shadowSoftness: 0.1,
  shadowCascadeCount: 4,
);

scene.directionalLight = light;
```

--------------------------------

### Split-Screen Example with RenderView

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/08-widgets.md

Demonstrates how to use RenderView to create a split-screen effect by assigning different viewports to two cameras. Each RenderView occupies half of the screen.

```dart
SceneView(
  scene,
  viewsBuilder: (elapsed) => [
    RenderView(
      camera: leftCamera,
      viewport: Rect.fromLTWH(0, 0, 0.5, 1),  // Left half
    ),
    RenderView(
      camera: rightCamera,
      viewport: Rect.fromLTWH(0.5, 0, 0.5, 1),  // Right half
    ),
  ],
)
```

--------------------------------

### Basic CMake Configuration

Source: https://github.com/bdero/flutter_scene/blob/master/examples/smoke_render/linux/runner/CMakeLists.txt

Sets the minimum CMake version and project name. This is a standard starting point for CMake projects.

```cmake
cmake_minimum_required(VERSION 3.13)
project(runner LANGUAGES CXX)
```

--------------------------------

### Enable Dart Data Assets

Source: https://github.com/bdero/flutter_scene/blob/master/README.md

One-time setup command to enable Dart data assets, specifically for DataAssets-backed .fmat materials.

```sh
flutter config --enable-dart-data-assets
```

--------------------------------

### SceneTickCallback Example Usage

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/08-widgets.md

Example of implementing a SceneTickCallback to update animations, physics, and custom game logic per frame.

```dart
onTick: (elapsed, deltaSeconds) {
  // Advance animations
  animationClip.update(Duration(milliseconds: (deltaSeconds * 1000).toInt()));
  
  // Update physics
  physicsWorld.step(deltaSeconds);
  
  // Custom logic
  updateAI(deltaSeconds);
}
```

--------------------------------

### Mesh Cloning Example

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/05-mesh.md

Shows how to clone a mesh and then customize the materials of specific primitives on each clone. This allows for per-instance material variations.

```dart
final original = await Node.fromGlbAsset('assets/character.glb');
final instance1 = original.clone();
final instance2 = original.clone();

// Customize each clone's materials independently
instance1.mesh?.primitives[0].material = redMaterial;
instance2.mesh?.primitives[0].material = blueMaterial;
```

--------------------------------

### ShaderMaterial Example

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/04-material.md

Loads a shader bundle, creates a ShaderMaterial with a custom fragment shader, and applies it to a mesh.

```dart
import 'package:flutter_scene/gpu.dart' as gpu;

final shaderLibrary = await gpu.loadShaderLibraryAsync('my_shader.shaderbundle');
final material = ShaderMaterial(
  fragmentShader: shaderLibrary['CustomFragment']!,
);

final geometry = PlaneGeometry(width: 1, height: 1);
final mesh = Mesh(geometry, material);
node.mesh = mesh;
```

--------------------------------

### Instantiate SkyEnvironment with Physical Sky

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/environment.md

Example of creating a SkyEnvironment using a PhysicalSkySource and setting it to derive the scene's environment map.

```dart
// Physical sky with environment
final sky = SkyEnvironment(
  source: PhysicalSkySource(sunIntensity: 2.0),
  appliesEnvironment: true,  // Environment derived from sky
);

// Use as scene background and IBL
scene.skyEnvironment = sky;
```

--------------------------------

### Texture Upload Example

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/gpu-shaders.md

Demonstrates how to create a texture and upload pixel data to it using the overwrite method. The texture is created as host-visible for easy data transfer.

```dart
final width = 256;
final height = 256;
final pixels = Uint8List(width * height * 4);  // RGBA

// Fill pixels...

final texture = gpu.gpuContext.createTexture(
  gpu.StorageMode.hostVisible,
  width,
  height,
);
texture!.overwrite(ByteData.view(pixels.buffer));
```

--------------------------------

### Install flutter_scene_rapier

Source: https://github.com/bdero/flutter_scene/blob/master/packages/flutter_scene_rapier/README.md

Add the flutter_scene and flutter_scene_rapier packages to your pubspec.yaml file.

```yaml
dependencies:
  flutter_scene: ^0.16.0
  flutter_scene_rapier: ^0.1.0
```

--------------------------------

### Get Workspace Dependencies

Source: https://github.com/bdero/flutter_scene/blob/master/README.md

Resolves dependencies for the pub workspace. Run this command first after cloning the repository.

```sh
flutter pub get
```

--------------------------------

### UnlitMaterial Example

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/04-material.md

Creates an UnlitMaterial and applies a red tint using colorFactor.

```dart
final material = UnlitMaterial(colorTexture: flatColor);
material.colorFactor = Vector4(1, 0, 0, 1);  // Red tint
```

--------------------------------

### Render to Texture Example with RenderView

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/08-widgets.md

Shows how to render a scene to a RenderTexture using RenderView and then utilize that texture within a material. This is useful for effects like mini-maps or reflections.

```dart
final renderTexture = RenderTexture(
  width: 512,
  height: 512,
  sampling: RenderTextureSampling.linear,
);

SceneView(
  scene,
  viewsBuilder: (elapsed) => [
    RenderView(
      camera: miniCamera,
      renderTexture: renderTexture,
    ),
  ],
)

// Use renderTexture in a material:
final material = PhysicallyBasedMaterial()
  ..baseColorTexture = renderTexture;
```

--------------------------------

### Complete Post-Process Configuration Example

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/11-post-processing.md

Apply a comprehensive set of post-processing effects, including bloom, color grading, film grain, and vignette, to a scene.

```dart
scene.postProcess = PostProcessSettings(
  bloom: BloomSettings(
    threshold: 0.8,
    intensity: 1.5,
    width: 12.0,
    iterations: 6,
  ),
  colorGrading: ColorGradingSettings(
    saturation: Vector3(1.1, 1.0, 1.0),  // Slightly warm
    contrast: Vector3(1.1, 1.1, 1.1),    // Punchier
    temperature: 6000.0,
  ),
  filmGrain: FilmGrainSettings(intensity: 0.05),
  vignette: VignetteSettings(intensity: 0.2, radius: 0.8),
);
```

--------------------------------

### Create a Dynamic RigidBody

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/10-physics.md

Example of creating a dynamic rigid body with specified mass and damping. This body will be affected by forces and gravity. It also shows how to apply an initial linear velocity.

```dart
final body = RigidBody(
  type: BodyType.dynamic,
  mass: 2.0,
  linearDamping: 0.2,
  angularDamping: 0.2,
);

node.addComponent(body);

// Apply force
body.linearVelocity = Vector3(5, 0, 0);
```

--------------------------------

### Build from Source Configuration

Source: https://github.com/bdero/flutter_scene/blob/master/packages/flutter_scene_rapier/README.md

Set the environment variable to build the native shim from source instead of downloading a prebuilt binary.

```sh
FLUTTER_SCENE_RAPIER_BUILD_FROM_SOURCE=1
```

--------------------------------

### Create and Display a Scene

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/README.md

This snippet demonstrates the basic steps to create a scene, load a GLB model, set up a camera, and render it within a SceneView widget. Ensure the model asset is correctly placed in the 'assets' folder.

```dart
import 'package:flutter_scene/scene.dart';

// 1. Create scene
final scene = Scene();

// 2. Load a model
final node = await Node.fromGlbAsset('assets/model.glb');
scene.add(node);

// 3. Set up camera
final camera = PerspectiveCamera(
  position: Vector3(0, 2, 5),
  target: Vector3.zero(),
);

// 4. Render in widget
SceneView(
  scene,
  camera: camera,
)
```

--------------------------------

### EnvironmentMap.studio()

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/environment.md

Creates an EnvironmentMap using the built-in studio environment, which provides warm neutral lighting.

```APIDOC
## EnvironmentMap.studio()

### Description
Creates an EnvironmentMap using the built-in studio environment, which provides warm neutral lighting.

### Returns
- EnvironmentMap: An EnvironmentMap object representing the studio environment.
```

--------------------------------

### EnvironmentMap Initialization

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/07-lighting.md

Demonstrates how to create an EnvironmentMap using built-in presets, from an asset file, or from a custom equirectangular texture.

```dart
import 'package:flutter_scene/scene.dart' show EnvironmentMap;

// Built-in environment
final env = EnvironmentMap.studio();

// From asset
final env = await EnvironmentMap.fromAsset('assets/env.png');

// Custom: equirectangular HDR image
final texture = await gpuTextureFromAsset('assets/ibl.hdr');
final env = EnvironmentMap.equirectangular(texture);
```

--------------------------------

### MeshPrimitive Material Update

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/05-mesh.md

Example of updating the material of an existing MeshPrimitive to change its appearance.

```dart
final primitive = MeshPrimitive(geometry, material);
primitive.material = newMaterial;  // Reskin
```

--------------------------------

### Setting Primitive Type for Geometry

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/05-mesh.md

Example of setting the primitive type for an UnskinnedGeometry instance to render line strips.

```dart
// Line geometry
final lineGeometry = UnskinnedGeometry();
lineGeometry.primitiveType = gpu.PrimitiveType.lineStrip;
lineGeometry.uploadVertexData(lineVertices, vertexCount, null);
```

--------------------------------

### Apply Environment Map to Material

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/environment.md

Demonstrates how to create an `EnvironmentMap` using `studio()` or `fromAsset()` and then apply it to a `PhysicallyBasedMaterial`. The environment can also be set scene-wide as a default.

```dart
// Built-in studio lighting
final env = EnvironmentMap.studio();

// Custom environment from asset
final customEnv = await EnvironmentMap.fromAsset('assets/environments/sunset.hdr');

// Use in materials
final material = PhysicallyBasedMaterial(
  environment: customEnv,
);

// Or set scene-wide (used as default for all materials)
// (Set via material.environment for per-material override)
```

--------------------------------

### Wiring Up a Custom Post-Processing Effect

Source: https://github.com/bdero/flutter_scene/blob/master/POST_PROCESSING.md

Demonstrates how to load a shader library, create a PostEffect instance, set its parameters, and add it to the scene's post-processing pipeline.

```dart
import 'package:flutter_scene/gpu.dart' as gpu;
import 'package:flutter_scene/scene.dart';

final library = await gpu.loadShaderLibraryAsync(
  'build/shaderbundles/my_bundle.shaderbundle',
);

final effect = PostEffect(
  fragmentShader: library!['WaveFragment']!,
  insertion: PostInsertion.beforeTonemap,
  useFrameInfo: true,
)..setUniformBlockFromFloats('WaveInfo', [
    0.008, // amplitude
    24.0,  // frequency
    3.0,   // speed
    0.0,   // padding
  ]);

scene.postProcess.customEffects.add(effect);
```

--------------------------------

### Initialize PerspectiveCamera

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/03-camera.md

Create a new PerspectiveCamera instance with custom position, target, and up vectors. Useful for setting up a camera at a specific viewpoint in the scene.

```dart
final camera = PerspectiveCamera(
  position: Vector3(0, 2, 5),
  target: Vector3.zero(),
  up: Vector3(0, 1, 0),
);
```

--------------------------------

### Node.fromGlbBytes

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/09-asset-loading.md

Loads a glTF binary file from raw bytes. This is useful when the GLB data is already in memory, for example, after downloading it from a network.

```APIDOC
## Node.fromGlbBytes

### Description
Loads a glTF binary from raw bytes.

### Method
`static Future<Node> fromGlbBytes(
  Uint8List bytes,
  {
  GltfResourceResolver? resolver,
  FsceneComponentRegistry? componentRegistry,
}
)`

### Parameters
#### Path Parameters
- **bytes** (Uint8List) - Required - Raw GLB file bytes

#### Query Parameters
- **resolver** (GltfResourceResolver?) - Optional - Resolver for external buffers/images
- **componentRegistry** (FsceneComponentRegistry?) - Optional - Custom component codec registry

### Response
#### Success Response
- **Future<Node>** - The root node.

### Example
```dart
final bytes = await rootBundle.load('assets/model.glb');
final root = await Node.fromGlbBytes(bytes.buffer.asUint8List());
```
```

--------------------------------

### Loading Animations from Assets

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/06-animation.md

Shows how to load animations from glTF binary files or preprocessed fscene packages.

```dart
// glTF binary
final node = await Node.fromGlbAsset('assets/model.glb')
// Animations are attached to the imported node graph

// fscene package (preprocessed)
final root = await loadScene('assets/levels/forest.glb')
// Animations accessible via node.createAnimationClip(...)
```

--------------------------------

### Mark Transform Dirty Example

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/02-node.md

Demonstrates how to modify a node's local transform translation and then mark it as dirty to update its world transform.

```dart
node.localTransform.setTranslation(Vector3(1, 2, 3));
node.markTransformDirty();
```

--------------------------------

### Add Node with Multiple Components

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/component.md

Demonstrates how to create a Node and add various components like MeshComponent, RigidBody, Collider, and custom behavior. Shows how to add the node to the scene and query for components.

```dart
import 'package:flutter_scene/scene.dart';

// 1. Create node
final node = Node(name: 'player');

// 2. Add mesh
node.addComponent(MeshComponent(Mesh(geometry, material)));

// 3. Add physics
node.addComponent(RigidBody(
  type: BodyType.dynamic,
  mass: 2.0,
));
node.addComponent(Collider(
  shape: CapsuleShape(radius: 0.5, halfHeight: 1.0),
));

// 4. Add custom behavior
node.addComponent(MyPlayerController());

// 5. Add to scene
scene.add(node);

// 6. Query/remove as needed
final physics = node.findComponent<RigidBody>();
if (physics != null) {
  physics.linearVelocity = Vector3(5, 0, 0);
}
```

--------------------------------

### Load glTF/GLB from Bytes

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/09-asset-loading.md

Load a glTF binary file from raw byte data. This is useful when the GLB data is already in memory, for example, after being downloaded.

```dart
final bytes = await rootBundle.load('assets/model.glb');
final root = await Node.fromGlbBytes(bytes.buffer.asUint8List());
```

--------------------------------

### Scene Constructor

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/01-scene.md

Creates a new Scene instance. Initializes static GPU resources and requires a usable Flutter GPU context.

```APIDOC
## Scene()

### Description
Creates a new scene with an empty root node. Initializes static GPU resources on first instantiation.

**Throws:** Exception if no usable Flutter GPU context is available.
```

--------------------------------

### Mark Local Bounds Dirty Example

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/05-mesh.md

Demonstrates invalidating the local bounds after updating a primitive's geometry. This ensures that subsequent calculations using the bounds are accurate.

```dart
mesh.primitives[0].geometry = newGeometry;
mesh.markLocalBoundsDirty();
```

--------------------------------

### Create a New Scene

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/01-scene.md

Instantiates a Scene object. This should be done once per scene. Initializes static GPU resources on first instantiation.

```dart
final scene = Scene();
```

--------------------------------

### Create Studio Environment Map

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/environment.md

Use the `studio()` factory method to create a default environment map with warm neutral lighting. This is useful for general-purpose scene lighting.

```dart
static EnvironmentMap studio()
```

--------------------------------

### System Dependencies with PkgConfig

Source: https://github.com/bdero/flutter_scene/blob/master/examples/smoke_render/linux/CMakeLists.txt

Finds and checks for GTK+ 3.0 system library using PkgConfig.

```cmake
find_package(PkgConfig REQUIRED)
pkg_check_modules(GTK REQUIRED IMPORTED_TARGET gtk+-3.0)
```

--------------------------------

### Get Frustum - Camera

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/03-camera.md

Returns the camera frustum, defined by six normalized clip planes. This is primarily used for culling objects that are outside the camera's view.

```dart
Frustum getFrustum(Size dimensions)
```

--------------------------------

### PerspectiveCamera Constructor

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/03-camera.md

Initializes a new PerspectiveCamera with specified world-space position, look-at target, up direction, and lens configuration.

```APIDOC
## PerspectiveCamera Constructor

### Description
Initializes a new PerspectiveCamera with specified world-space position, look-at target, up direction, and lens configuration.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Constructor Signature
```dart
PerspectiveCamera({
  Vector3? position,
  Vector3? target,
  Vector3? up,
  CameraProjection? projection,
})
```

### Parameters
- **position** (Vector3?) - Optional - World-space eye. Defaults to Vector3(0, 0, 5).
- **target** (Vector3?) - Optional - Look-at point. Defaults to Vector3.zero().
- **up** (Vector3?) - Optional - World-space up. Defaults to Vector3(0, 1, 0).
- **projection** (CameraProjection?) - Optional - Lens configuration. Defaults to PerspectiveProjection().

### Example
```dart
final camera = PerspectiveCamera(
  position: Vector3(0, 2, 5),
  target: Vector3.zero(),
  up: Vector3(0, 1, 0),
);
```
```

--------------------------------

### Get View Matrix - Camera

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/03-camera.md

Returns the world-to-view transform matrix, independent of render target size. This is useful for calculating camera orientation and position in world space.

```dart
Matrix4 getViewMatrix()
```

--------------------------------

### Create a Kinematic RigidBody

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/10-physics.md

Example of creating a kinematic rigid body. This type is typically used for objects driven by animation, such as platforms. Its transform should be updated manually in the animation loop.

```dart
// Animation-driven platform
final platform = RigidBody(
  type: BodyType.kinematic,
);
platformNode.addComponent(platform);

// In onTick, animate the node transform
```

--------------------------------

### Get Placeholder Textures

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/04-material.md

Provides static methods to retrieve 1x1 placeholder textures (white, normal, black) for missing texture slots. These are lazily created on first use.

```dart
static gpu.Texture getWhitePlaceholderTexture()
static gpu.Texture whitePlaceholder(gpu.Texture? texture)

static gpu.Texture getNormalPlaceholderTexture()
static gpu.Texture normalPlaceholder(gpu.Texture? texture)

static gpu.Texture getBlackPlaceholderTexture()
```

--------------------------------

### Physics Simulation

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/README.md

This snippet demonstrates how to set up a physics simulation by adding a PhysicsWorld to the scene and creating dynamic rigid bodies with colliders. The physics world needs to be stepped each frame using the delta time.

```dart
final physicsWorld = PhysicsWorld();
scene.add(physicsWorld);

// Create dynamic body
final body = RigidBody(type: BodyType.dynamic, mass: 2.0);
final collider = Collider(shape: SphereShape(radius: 0.5));
node.addComponent(body);
node.addComponent(collider);

// Step physics each frame
scene.onTick = (elapsed, deltaSeconds) {
  physicsWorld.step(deltaSeconds);
};
```

--------------------------------

### Configure buildScenes Build Hook

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/09-asset-loading.md

Sets up the build hook to preprocess .glb files into .fsceneb packages for efficient scene loading. This configuration is part of the build process.

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

void main(List<String> args) {
  buildScenes(args);
}
```

--------------------------------

### RenderView Class Definition

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/08-widgets.md

Defines a render-to-texture target or view within a multi-view render setup. It specifies the camera, optional render texture, viewport, scissor region, and layer mask.

```dart
class RenderView {
  RenderView({
    required this.camera,
    this.renderTexture,
    this.viewport = const Rect.fromLTWH(0, 0, 1, 1),
    this.scissor,
    this.layerMask = kRenderLayerDefault,
  });
}
```

--------------------------------

### Loading glTF/GLB

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/02-node.md

Static methods to load glTF binary files (.glb or .gltf+.bin) at runtime. These methods return a node graph representing the imported scene and support custom resource resolution and component registries.

```APIDOC
## Loading glTF/GLB

### Description
Loads a glTF binary (`.glb` or `.gltf+.bin`) at runtime, returning a node graph.

### Method Signatures
```dart
static Future<Node> fromGlbBytes(
  Uint8List bytes,
  {
  GltfResourceResolver? resolver,
  FsceneComponentRegistry? componentRegistry,
}
)

static Future<Node> fromGlbAsset(
  String assetPath,
  {
  AssetBundle? bundle,
  FsceneComponentRegistry? componentRegistry,
}
)
```

### Parameters
#### fromGlbBytes
- **bytes** (Uint8List) - Required - Raw GLB bytes
- **resolver** (GltfResourceResolver?) - Optional - Custom resolver for external buffers/images
- **componentRegistry** (FsceneComponentRegistry?) - Optional - Custom component codec registry

#### fromGlbAsset
- **assetPath** (String) - Required - Flutter asset path
- **bundle** (AssetBundle?) - Optional - Asset bundle override
- **componentRegistry** (FsceneComponentRegistry?) - Optional - Custom component codec registry

### Returns
- **Future<Node>** - Future resolving to the root node of the imported scene.

### Throws
- **FormatException** - On invalid glTF.

### Example
```dart
final node = await Node.fromGlbAsset('assets/model.glb');
scene.add(node);
```
```

--------------------------------

### Add a Widget Component to a Node

Source: https://github.com/bdero/flutter_scene/blob/master/WIDGETS.md

This snippet shows the basic setup for adding a Flutter widget to a scene node. It configures the widget's size, pixel ratio, and world height.

```dart
scene.add(
  Node(name: 'panel')
    ..addComponent(WidgetComponent(
      size: const Size(480, 300),   // the widget's logical layout size
      pixelRatio: 2.0,              // texels per logical pixel
      worldHeight: 1.5,             // world units; width follows the aspect
      child: const MyControlPanel(),
    )),
);

```

--------------------------------

### Define a Custom Rotating Component

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/component.md

Extend the base Component class to add custom behaviors like rotation. This example shows how to implement `onMount`, `onUnmount`, and `update` methods for a rotating component.

```dart
class RotatingComponent extends Component {
  double rotationSpeedRadiansPerSecond = 1.0;
  Stopwatch _stopwatch = Stopwatch();
  
  @override
  void onMount() {
    _stopwatch.start();
  }
  
  @override
  void onUnmount() {
    _stopwatch.stop();
  }
  
  void update(double deltaSeconds) {
    final angle = rotationSpeedRadiansPerSecond * deltaSeconds;
    node.localTransform.rotate(Vector3(0, 1, 0), angle);
  }
}
```

--------------------------------

### Enable Native Asset Builds

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/README.md

Enable native asset builds and Dart data assets using Flutter configuration commands.

```bash
flutter config --enable-native-assets
flutter config --enable-dart-data-assets
```

--------------------------------

### Widget Component with Custom Material and Binding

Source: https://github.com/bdero/flutter_scene/blob/master/WIDGETS.md

This snippet demonstrates how to use a custom material and provide a bind callback for more complex material setups. The bind callback is used to set textures on the material.

```dart
WidgetComponent(
  size: const Size(480, 300),
  geometry: crtScreen,
  material: crtMaterial,           // e.g. a ShaderMaterial from an .fmat
  bind: (texture) {
    crtMaterial.parameters.setTexture('screen_tex', texture);
    crtMaterial.parameters.setTexture('glow_tex', texture);
  },
  child: const MyControlPanel(),
)

```

--------------------------------

### Get View Transform - Camera

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/03-camera.md

Returns the combined projection-and-view matrix for a specific render target size. Use this when you need the final matrix to transform vertices from world space to clip space.

```dart
Matrix4 getViewTransform(Size dimensions)
```

--------------------------------

### Apply Standard Build Settings

Source: https://github.com/bdero/flutter_scene/blob/master/examples/smoke_render/linux/runner/CMakeLists.txt

Applies a predefined set of build settings to the target. This simplifies configuration for common build requirements.

```cmake
apply_standard_settings(${BINARY_NAME})
```

--------------------------------

### Mixed Approach: Preprocessed Scene with Runtime Customization

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/09-asset-loading.md

Combine preprocessed scenes with runtime glTF customization. Load a preprocessed scene and then add dynamically loaded runtime glTF models to it.

```dart
// Preprocessed scene + runtime glTF customization
final root = await loadScene('assets/levels/forest.glb');

// Load additional model at runtime
final prop = await Node.fromGlbAsset('assets/props/table.glb');
root.add(prop);

scene.add(root);
```

--------------------------------

### Scene Interaction Example with ScenePointer

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/08-widgets.md

Illustrates how to use ScenePointer methods within a GestureDetector to handle tap events. It converts the tap position to a ray and performs a raycast to detect intersections with scene nodes.

```dart
GestureDetector(
  onTapDown: (details) {
    final ray = camera.screenPointToRay(
      details.globalPosition,
      viewSize,
    );
    final hit = scene.raycast(ray);
    if (hit != null) {
      print('Hit: ${hit.node.name}');
    }
  },
)
```

--------------------------------

### SkyEnvironment Parameter Details

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/environment.md

Provides details on the parameters for the SkyEnvironment constructor, including source, appliesEnvironment, and refresh frequency.

```markdown
| Parameter | Type | Default |
|-----------|------|---------|
| source | SkySource | — |
| appliesEnvironment | bool | true |
| refresh | SkyEnvironmentRefresh | everyFrame |
```

--------------------------------

### Custom Resource Resolver for glTF

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/09-asset-loading.md

Implement a custom resolver to handle external resources like buffers and images referenced in multi-file glTF documents. This example shows how to resolve relative URIs to Flutter assets.

```dart
typedef GltfResourceResolver = Future<Uint8List> Function(String uri);

Future<Node> loadGltfWithResources(String mainAsset) {
  return Node.fromGlbAsset(
    mainAsset,
    resolver: (uri) async {
      // Resolve relative URIs (e.g., "model.bin" → "assets/models/model.bin")
      final resolved = Uri.parse(uri);
      final bytes = await rootBundle.load('assets/models/$uri');
      return bytes.buffer.asUint8List();
    },
  );
}
```

--------------------------------

### Regenerate Attribution Manifest

Source: https://github.com/bdero/flutter_scene/blob/master/packages/flutter_scene_rapier/THIRD_PARTY_NOTICES.md

This command-line instruction shows how to regenerate a complete, machine-verified attribution manifest for the third-party crates used by the package. It requires either `cargo about` or `cargo license` to be installed and run against the `native/` directory.

```bash
cargo about \
  (or `cargo license`) \
  against `native/`.
```

--------------------------------

### Blending Multiple Animations

Source: https://github.com/bdero/flutter_scene/blob/master/_autodocs/06-animation.md

Attach multiple animation clips to the same node and control their blend weights. The example demonstrates a crossfade transition between two clips over a specified duration. Weights are automatically normalized if their sum exceeds 1.0.

```dart
final runClip = node.createAnimationClip(runAnimation)!;
final aimClip = node.createAnimationClip(aimAnimation)!;

runClip.weight = 0.7;
aimClip.weight = 0.3;
// Normalized: run 70%, aim 30%

// Transition: crossfade over time
var blendTime = 0.0;
scene.onTick = (elapsed, deltaSeconds) {
  blendTime += deltaSeconds;
  final t = (blendTime / transitionDuration).clamp(0, 1);
  runClip.weight = 1 - t;
  aimClip.weight = t;
  scene.update(Duration(milliseconds: (deltaSeconds * 1000).toInt()));
};
```

--------------------------------

### Create Flutter Project for Web

Source: https://github.com/bdero/flutter_scene/blob/master/examples/flutter_gpu_shim_smoke/README.md

Command to create a new Flutter project or scaffold existing ones for web platform support.

```sh
flutter create . --platforms=web
```

--------------------------------

### WebAssembly Runtime Configuration

Source: https://github.com/bdero/flutter_scene/blob/master/packages/flutter_scene_rapier/README.md

Configure the web runtime to load the WebAssembly module from a specific URL during development.

```sh
flutter run -d chrome \
  --dart-define=FLUTTER_SCENE_RAPIER_WASM_URL=/flutter_scene_rapier_native.wasm
```