mob-sakai / UIMaterialPropertyInjector

This package provides a component that allows easy modification/animation of material properties for Unity UI (uGUI) without the need for shader-specific custom components.

UI Material Property Injector

<< 🎮 Demo | ⚙ Installation | 🚀 Usage | 🤝 Contributing >>

📝 Description

In Unity UI, UI elements typically do not provide an accessible MaterialPropertyBlock. To change material properties via animations, like with MeshRenderer, you usually need to create custom components, which are often shader-specific.

Custom properties for changing material properties are easy for experienced users but can be a high hurdle for beginners:

• Are material assets being changed directly?
• Are material instances leaking?
• Is it allocating unnecessarily every time the property changes?
• Does it support masks?
• Does it support animations?
• And so on.

This package provides a component that allows easy modification of material properties for Unity UI (uGUI) without the need for shader-specific custom components.

Key Features:

• Change UI material properties without shader-specific custom components.
• Modify material properties:
  • via animation, similar to MeshRenderer
  • via tweener component
  • via code
  • via the inspector
• Automatic creation and deletion of material instances.
• Instead of creating material assets with slight differences, you can create material instances and change properties.
• Share material instances by specifying a GroupId.
• Automatic detection of shader properties.
• Supports the Mask component.
• Supports TextMeshProUGUI and SubMeshUI components. (uGUI 2.0 ready)
• Good performance.

🎮 Demo

WebGL Demo

⚙ Installation

This package requires Unity 2019.4 or later.

Install via OpenUPM

• This package is available on OpenUPM package registry.
• This is the preferred method of installation, as you can easily receive updates as they're released.
• If you have openupm-cli installed, then run the following command in your project's directory:

  openupm add com.coffee.ui-material-property-injector
  

• To update the package, use Package Manager UI (Window > Package Manager) or run the following command with @{version}:

  openupm add com.coffee.ui-material-property-injector@1.0.0
  

Install via UPM (with Package Manager UI)

• Click Window > Package Manager to open Package Manager UI.
• Click + > Add package from git URL... and input the repository URL: https://github.com/mob-sakai/UIMaterialPropertyInjector.git?path=Packages/src
  
• To update the package, change suffix #{version} to the target version.
  • e.g. https://github.com/mob-sakai/UIMaterialPropertyInjector.git?path=Packages/src#1.0.0

Install via UPM (Manually)

• Open the Packages/manifest.json file in your project. Then add this package somewhere in the dependencies block:

  {
    "dependencies": {
      "com.coffee.ui-material-property-injector": "https://github.com/mob-sakai/UIMaterialPropertyInjector.git?path=Packages/src",
      ...
    }
  }

• To update the package, change suffix #{version} to the target version.

  • e.g. "com.coffee.ui-material-property-injector": "https://github.com/mob-sakai/UIMaterialPropertyInjector.git?path=Packages/src#1.0.0",

Install as Embedded Package

1. Download a source code zip file from Releases and extract it.
2. Place it in your project's Packages directory.
   

• If you want to fix bugs or add features, install it as an embedded package.
• To update the package, you need to re-download it and replace the contents.

🚀 Usage

1. Add the UIMaterialPropertyInjector component to a graphic (Image, RawImage, Text, etc.) and mark the shader properties as injectable.
   
2. Change the properties via animation, code or tweener.

   var injector = GetComponent<UIMaterialPropertyInjector>();
   injector.SetFloat("_Intensity", 0.9f);

3. Enjoy!

UI Material Property Injector

Change the material properties of the CanvasRenderer.

• Reset Values On Enable: Reset injector values with the material properties when the component is enabled.
• Animatable: Makes it animatable in the Animation view.
• Shared Group Id: Share material instances by specifying a GroupId.
  • NOTE: The material instances cannot be shared if the mask depth is different.
• Properties: Shader properties to inject.
  • Click Reset Values to reset injector values to the material properties.

UI Material Property Tweener

A tweener to change the material properties.

• Target: The target UIMaterialPropertyInjector to tween.
• Curve: The curve to tween the properties.
• Delay: The delay in seconds before the tween starts.
• Duration: The duration in seconds of the tween.
• Interval: The interval in seconds between each loop.
• Restart On Enable: Whether to restart the tween when enabled.
• Wrap Mode: The wrap mode of the tween.
  • Clamp: Clamp the tween value, not loop.
  • Loop: Loop the tween value.
  • PingPongOnce: PingPong the tween value, not loop.
  • PingPong: PingPong the tween value.
• Update Mode: Specifies how to get delta time.
  • Normal: Use Time.deltaTime.
  • Unscaled: Use Time.unscaledDeltaTime.
  • Manual: Not updated automatically and update manually with UpdateTime or SetTime method.
• Properties: Shader properties to inject. The tweener interpolates two values with an animation curve.
  • Click Reset Values to reset injector values to the material properties.
    
    

🤝 Contributing

Issues

Issues are incredibly valuable to this project:

• Ideas provide a valuable source of contributions that others can make.
• Problems help identify areas where this project needs improvement.
• Questions indicate where contributors can enhance the user experience.

Pull Requests

Pull requests offer a fantastic way to contribute your ideas to this repository.
Please refer to CONTRIBUTING.md and develop branch for guidelines.

Support

This is an open-source project developed during my spare time.
If you appreciate it, consider supporting me.
Your support allows me to dedicate more time to development. 😊

License

• MIT

Author

• mob-sakai

See Also

• GitHub page : https://github.com/mob-sakai/UIMaterialPropertyInjector
• Releases : https://github.com/mob-sakai/UIMaterialPropertyInjector/releases
• Issue tracker : https://github.com/mob-sakai/UIMaterialPropertyInjector/issues
• Change log : https://github.com/mob-sakai/UIMaterialPropertyInjector/blob/main/CHANGELOG.md