{"id":16181335,"url":"https://github.com/ethereumdegen/bevy_material_tool","last_synced_at":"2026-02-12T09:31:04.386Z","repository":{"id":254527130,"uuid":"846811703","full_name":"ethereumdegen/bevy_material_tool","owner":"ethereumdegen","description":null,"archived":false,"fork":false,"pushed_at":"2024-11-10T18:55:49.000Z","size":1661,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-02T21:11:13.236Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ethereumdegen.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-24T03:01:35.000Z","updated_at":"2025-03-06T13:16:13.000Z","dependencies_parsed_at":"2024-09-05T22:23:51.820Z","dependency_job_id":"c327bbc6-6f56-4908-93f5-01399a38fcfd","html_url":"https://github.com/ethereumdegen/bevy_material_tool","commit_stats":null,"previous_names":["ethereumdegen/bevy_material_tool"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ethereumdegen/bevy_material_tool","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethereumdegen%2Fbevy_material_tool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethereumdegen%2Fbevy_material_tool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethereumdegen%2Fbevy_material_tool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethereumdegen%2Fbevy_material_tool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ethereumdegen","download_url":"https://codeload.github.com/ethereumdegen/bevy_material_tool/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethereumdegen%2Fbevy_material_tool/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29362768,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-12T08:51:36.827Z","status":"ssl_error","status_checked_at":"2026-02-12T08:51:26.849Z","response_time":55,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-10T06:24:40.669Z","updated_at":"2026-02-12T09:31:04.367Z","avatar_url":"https://github.com/ethereumdegen.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":" \n\n# Material Overrides Tool for Bevy\n\nThis Rust crate provides functionality for loading materials from a `.glb` file and additional material configuration data from a separate file. It supports hot-swapping materials in a Bevy scene using two custom components: `MaterialOverrideComponent` and `MaterialOverrideWhenSceneReadyComponent`.\n\n## Features\n\n- **Material Loading**: Automatically load materials from a specified `.glb` file and apply additional configurations, such as UV scaling and color tinting, from a separate configuration file.\n- **Hot-Swapping**: Dynamically swap materials in the scene using the `MaterialOverrideComponent` and `MaterialOverrideWhenSceneReadyComponent`.\n- **Flexible Configuration**: Customize materials using a configuration file that allows for UV scale adjustments and diffuse color tinting.\n\n\n\n### Define your materials like this: \n\n![image](https://github.com/user-attachments/assets/1d5fda33-8916-4dbd-95aa-c10f22041939)\n\n\n\n\n## Getting Started\n\n### 1. Installation\n\nTo use this crate, add it to your `Cargo.toml`:\n\n```\ncargo add bevy_material_tool\n```\n\n### 2. Usage\n\n#### Setting Up the Plugin\n\nFirst, set up the `plugin` in your Bevy application:\n\n```rust\n\n    app.add_plugins(BevyMaterialToolPlugin{\n                    material_types_config_path: \"assets/material_overrides/material_types.ron\".to_string(),\n                    material_overrides_gltf_path : \"material_overrides/doodad_material_overrides.glb\".to_string()\n            }  );\n\n \n```\n\n\n#### Configuring Material Overrides\n\nMaterial override means that every child of the entity that has a handle\u003cmesh\u003e will have its handle\u003cmaterial\u003e overridden by the specified material, indexed by string.  \n\n\nThe plugin uses either of two components to manage material overrides:\n\n1. **`MaterialOverrideComponent`**: Attach this component to entities that require material replacement immediately. \n   \n   ```rust\n   commands.entity(entity)\n       .insert(MaterialOverrideComponent {\n           material_override: \"Wall1\".to_string(),\n       });\n   ```\n\n2. **`MaterialOverrideWhenSceneReadyComponent`**: Use this component to defer material overrides until the scene is ready.\n\n   ```rust\n   commands.entity(entity)\n       .insert(MaterialOverrideWhenSceneReadyComponent {\n           material_override: \"StoneToon1\".to_string(),\n       });\n   ```\n\n\nTake care not to add these components until after 'MaterialOverridesLoadingState::Complete' state has been entered.  !\n\n\n#### Configuring Material Replacements \n\nTo use material replacement, you need to load your GLTFs in a special way:  First you must load the GLTF into the asset server (not the scene!) and then to attach it to your entity to see it in engine , you would use something like 'AddGltfModelComponent' in gltf_models.rs.  \n\nThis way, the material_name_map plugin will be able to index every single named material in every GLTF you load into its resource and add a 'MaterialMetadataName' component to each entity with handle\u003cStandardMaterial\u003e loaded this way. \n\n\nMaterial replacement means that you specify a HashMap\u003cString,String\u003e (old material name -\u003e new material name)  and then every child of the entity will be inspected for a 'MaterialMetadataName' component .  If that exists, and if its material name (from blender) matches any of thte 'keys' of the replacement hashmap, then that material will be swapped out for the new material using MaterialOverride.  \n\nWhile MaterialOverride component only lets you make a GLTFs meshes all use a single material, MaterialReplacements component allows you to swap multiple materials for multiple other materials, surgically.  \n\n\n#### Loading Materials\n\nThe materials are loaded from a `.glb` file specified in the `MaterialOverridesResource`:\n\n\n### 3. Configuration File\n\nThe material configuration file is a RON (Rusty Object Notation) file that defines the material types and their properties, such as UV scale and color tint.\n\nExample `material_types_config.ron`:\n\n```ron\n(\n  material_types: {\n    //these keys are material names used for MaterialOverride.0 or for the values of MaterialReplacement. The values should match your materials in the blender file of the .glb material swatch template that gets extracted by material_overrides.rs.\n\n    \"Wall1\": (\n      material_name: \"Wall1\",\n      uv_scale_factor: 16.0,\n      diffuse_color_tint: Some(LinearRgba(\n        red: 1.0,\n        green: 1.0,\n        blue: 1.0,\n        alpha: 1.0,\n      )),\n    ),\n    \"StoneToon1\": (\n      material_name: \"StoneToon1\",\n      uv_scale_factor: 2.0,\n    ),\n    \"StoneToon2\": (\n      material_name: \"StoneToon2\",\n      uv_scale_factor: 2.0,\n    ),\n    \"DirtToon1\": (\n      material_name: \"DirtToon1\",\n      uv_scale_factor: 2.0,\n    ),\n    \"TiledWall1\": (\n      material_name: \"Wall1\",\n      uv_scale_factor: 1.0,\n    ),\n  }, \n\n\n  //this is optional and it makes material replacement more succinct.  You can use the component MaterialReplacementApplySetWhenSceneReadyComponent(\"tree_fir\") for example to specify that an entities children should experience material replacement according to the replacement map where the keys of the map are the material names in blender for the asset and the values are your custom material names defined as keys in material_types above.  \n\n    material_replacement_sets: Some( {\n\n\n    \"tree_fir\" : {\n\n        \"bark\" : \"TreeBark1\",\n        \"leaves\" : \"TreeLeavesFir\",\n        \"branches\": \"Branches1\"\n\n    },\n\n    \"tree_suntail\" : {\n\n        \"bark\" : \"Wood1\",\n        \"leaves\" : \"Leaves3\",\n        \"branches\": \"Branches1\"\n\n\n    }\n\n  } )\n)\n```\n\n### 4. Advanced Usage\n\n#### MaterialOverridesLoadingState\n\nThe crate defines a state machine to manage material loading and processing:\n\n- **`Init`**: Initial state.\n- **`Extracting`**: Extracts materials from the `.glb` file.\n- **`Building`**: Builds materials based on the configuration file.\n- **`Complete`**: All materials are loaded and ready.\n\nYou can customize or extend these states for more complex material management workflows.\n\n### 5. Contributing\n\nContributions are welcome! Please open an issue or submit a pull request on GitHub.\n\n### 6. License\n\nThe code in this project is licensed under the MIT License.  Texture/material assets are not included in this license.  See the [LICENSE](LICENSE) file for details.\n\n \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fethereumdegen%2Fbevy_material_tool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fethereumdegen%2Fbevy_material_tool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fethereumdegen%2Fbevy_material_tool/lists"}