Unity SBP Texture Replacement Example

This project demonstrates how to replace a Texture2D asset with another during an AssetBundle build using a custom IBuildTask in Unity's Scriptable Build Pipeline (SBP).

Overview

The core of this project is a Unity Editor test that builds AssetBundles for a simple prefab. The prefab (quad.prefab) uses a material (mat1.mat) which in turn uses a 32x32 texture (image1.png).

During the build process, a custom task (ReplaceTextureTask) intercepts the build pipeline and swaps image1.png with a different 4x4 texture (empty.png). The test then loads the resulting AssetBundles and verifies that the material on the instantiated prefab is using the replacement texture, confirming the swap was successful.

How It Works

The replacement is achieved via the ReplaceTextureTask, a custom implementation of SBP's IBuildTask.

1. Injection: The task is inserted into the default build task list just before the WriteSerializedFiles task.
2. Object Remapping: It identifies the ObjectIdentifier for both the original and replacement textures.
3. Data Swap: Before the bundle data is written to disk, the task iterates through the WriteOperations and replaces the serializationObject pointing to the original texture with the one for the replacement texture.
4. Result: The material's reference to the texture's object identifier remains unchanged, but the data associated with that identifier is now the replacement texture's data. When the bundle is loaded, the material uses the new texture.

The entire process is orchestrated and verified within a single NUnit test (Build_WithTextureReplacement_MaterialUsesReplacementTexture).

Core Components

• Assets/quad.prefab: A simple quad prefab with a MeshRenderer.
• Assets/mat1.mat: A material assigned to the quad, which uses image1.png.
• Assets/image1.png: The original 32x32 opaque texture.
• Assets/empty.png: The replacement 4x4 transparent texture.
• Assets/Tests/Editor/AssetBundleReplaceTest.cs: Contains the two main classes:
  • ReplaceTextureTask: The custom SBP build task that performs the texture swap.
  • AssetBundleReplaceTest: The NUnit test fixture that drives the build, load, and verification process.

How to Run the Test

1. Open the project in a compatible version of the Unity Editor.
2. Wait for the project to compile.
3. Open the Test Runner window via Window > General > Test Runner.
4. In the Test Runner, select the EditMode tab.
5. Click the Run All button or run the Build_WithTextureReplacement_MaterialUsesReplacementTexture test specifically.

Expected Outcome

The test will execute the following steps:

1. Build two AssetBundles (mat1_bundle and quad_bundle) into a temporary directory, replacing image1.png with empty.png during the process.
2. Load the bundles and instantiate the quad.prefab.
3. Assert that the mainTexture on the quad's material has a width and height of 4, matching the dimensions of empty.png.
4. Clean up by deleting the temporary directory and unloading all assets.

The test should pass, indicated by a green checkmark in the Test Runner, confirming the texture was successfully replaced at build time.