{"id":15651827,"url":"https://github.com/leoncvlt/three-extended-material","last_synced_at":"2025-04-30T20:05:20.342Z","repository":{"id":44712792,"uuid":"453190942","full_name":"leoncvlt/three-extended-material","owner":"leoncvlt","description":"🧱 Easily extend native three.js materials with modular and composable shader units and effects, available as a vanilla or React component","archived":false,"fork":false,"pushed_at":"2023-09-06T17:19:01.000Z","size":514,"stargazers_count":37,"open_issues_count":0,"forks_count":8,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-30T20:04:43.786Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://leoncvlt.github.io/three-extended-material/complex/","language":"JavaScript","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/leoncvlt.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":"2022-01-28T19:25:08.000Z","updated_at":"2025-03-04T12:40:48.000Z","dependencies_parsed_at":"2024-10-03T12:40:25.233Z","dependency_job_id":"a0a0c0ca-f13e-4530-810c-1bbb03d38d0c","html_url":"https://github.com/leoncvlt/three-extended-material","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leoncvlt%2Fthree-extended-material","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leoncvlt%2Fthree-extended-material/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leoncvlt%2Fthree-extended-material/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leoncvlt%2Fthree-extended-material/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/leoncvlt","download_url":"https://codeload.github.com/leoncvlt/three-extended-material/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251774894,"owners_count":21641731,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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-03T12:40:18.066Z","updated_at":"2025-04-30T20:05:20.323Z","avatar_url":"https://github.com/leoncvlt.png","language":"JavaScript","funding_links":["https://www.buymeacoffee.com/leoncvlt"],"categories":[],"sub_categories":[],"readme":"# three-extended-material\n\nEasily extend native three.js materials with modular and composable shader units and effects, available as a vanilla or React component.\n\n![image](https://user-images.githubusercontent.com/4929974/151654060-d44e7859-f966-4b0e-834e-0f7b13b60e21.png)\n\n## Usage\n```\nnpm install three-extended-material\n```\n\nThen, create your extended material:\n```js\nimport { ExtendedMaterial } from \"three-extended-material\"\n\nconst material = new ExtendedMaterial(\n\n    superMaterial,  // the threejs material class to extend\n\n    extensions,     // the extension (or an array of extensions) \n                    // object to extend the material with\n\n    parameters,     // the properties to pass the material \n                    // (can be either properties from the original material, \n                    // or uniforms from the extensions)\n\n    options         // additional options (explained later)\n)\n```\n\nAn extension is a simple object with the following signature:\n```js\nconst extension = {\n\n  name: \"\",         // string defining the name of the extension\n                    // used to generate a unique shader program code\n\n  uniforms: {},     // uniforms to pass to the materials, in a { uniform: value } format.\n                    // note that uniforms are not automatically prepended to the shader code.\n                    // be careful about not repeating uniform names when chaining extensions\n\n  defines: {},      // defines to pass to the materials, in a { define: 1 or 0 } format.\n\n  vertexShader: (shader, type) =\u003e shader,    // a function which takes the original vertex\n                                            // shader code, and returns the modified cone\n\n  fragmentShader: (shader, type) =\u003e shader,   // a function which takes the original fragment\n                                              // shader code, and returns the modified cone\n};\n```\nThe name of each extension is hashed alongside the name of the original material in order to generate a unique [shader program cache key](https://threejs.org/docs/?q=materi#api/en/materials/Material.customProgramCacheKey) for that combination.\n\nThe `ExtendedMaterial` will provide property accessors to all uniforms, so you can use `extension.myUniform` to set or get the value. This means that when using multiple extension, each uniform name should be unique.\n\nThe `vertexShader` and `fragmentShader` functions provide you with the original material shaders code, and should return the modified shader code to replace the original shaders code with. A common pattern is to prepend the uniforms definition to the code, and then run a string replace function to add extra shader code in specific places. The second argument `type` will be the type of the shader, and can be useful to support multiple SuperMaterials at once, by monkey-patch specific bits of thhe shader if the `type` is of `MeshBasicMaterial`, some other for `MeshPhysicalMaterial`, and so on.\n\nNote that when chaining multiple extensions, the shader code is modified for each extension, and passed to the next one - so be careful about not removing pieces of shader which might be queried by later extensions.\n\nYou can also pass an options object with any of the following parameters to the ExtendedMaterial constructor as the last argument:\n```js\n{\n  debug: false,           // if true, prints the material's shader code after being patched\n  programCacheKey: null   // if not null, sets the customProgramCacheKey \n                          // for the material to this value instead of hashing it.\n}\n```\n\nthree.js materials' shaders are pretty opinionated - a good starting point would be to use the `debug` option to print the original shader code, then exploring the [ShaderChunks definitions on GitHub](https://github.com/mrdoob/three.js/tree/master/src/renderers/shaders/ShaderChunk) to figure out a good injection point for your logic.\n\n## Example\nHere's a basic setup where we extend the `MeshStandardMaterial` with an extension which overlays a screen-space checkerboard:\n\n```js\nconst checkerBoardExtension = {\n  name: \"checkerboard\",\n  uniforms: {\n    checkersSize: 5.0,\n  },\n  // no defines or vertex shader modifications needed\n  // in this extension, so we can leave them out\n  fragmentShader: (shader, type) =\u003e {\n    shader = `\n      uniform float checkersSize;\n      ${shader.replace(\n        \"#include \u003copaque_fragment\u003e\",\n        // here we inject the checkerboard logic right before the \u003copaque_fragment\u003e,\n        // where gl_FragColor is set according to the lighting calculation\n        // https://github.com/mrdoob/three.js/blob/master/src/renderers/shaders/ShaderChunk/output_fragment.glsl.js\n        `\n        vec2 pos = floor(gl_FragCoord.xy / checkersSize);\n        float pattern = mod(pos.x + mod(pos.y, 2.0), 2.0);\n  \n        outgoingLight = outgoingLight * pattern;\n        #include \u003copaque_fragment\u003e\n        `\n      )}\n    `;\n    return shader;\n  },\n};\n\nconst material = new ExtendedMaterial(MeshStandardMaterial, [checkerBoardExtension], {\n  color: 0x00aaff,\n  checkersSize: 8.0, // we can pass different values than the default one...\n});\n\nconst box = new Mesh(new BoxGeometry(), material);\nbox.material.checkersSize: 10.0; //... or use the property accessor to set / get its value\n```\n\n## React\n\n`ExtendedMaterial` is also exported as a `react-three-fiber`-friendly component to be used in `React` projects:\n\n```jsx\nimport { ExtendedMaterial } from \"three-extended-material/react\"\nimport { MeshStandardMaterial } from 'three';\n\nfunction Box() {\n  return (\n    \u003cmesh\n      \u003cboxGeometry args={[1, 1, 1]} /\u003e\n      \u003cExtendedMaterial \n        superMaterial={MeshStandardMaterial} \n        extensions={[checkerBoardExtension]} \n        color={0x00aaff}\n        checkersSize={8.0}\n      /\u003e \n    \u003c/mesh\u003e\n  )\n}\n```\nIn this case, just pass the ExtendedMaterial's parameters to as props to the component, in the classic react declarative style. Its properties will be updated reactively, and the Material will be re-created only if the `superMaterial` or its `extensions` changes.\n\n## Demos\n\n- [three-extended-material/simple](https://leoncvlt.github.io/three-extended-material/simple/) - A demo of the checkerboard setup illustrated above\n- [three-extended-material/complex](https://leoncvlt.github.io/three-extended-material/complex/) - A more complex example with multiple toggleable extensions, editing properties in real-time and some interesting effects.\n- [three-extended-material/react](https://leoncvlt.github.io/three-extended-material/react/) - A demo of the checkerboard setup using `react-three-fiber`\n\n## Support [![Buy me a coffee](https://img.shields.io/badge/-buy%20me%20a%20coffee-lightgrey?style=flat\u0026logo=buy-me-a-coffee\u0026color=FF813F\u0026logoColor=white \"Buy me a coffee\")](https://www.buymeacoffee.com/leoncvlt)\nIf this tool has proven useful to you, consider [buying me a coffee](https://www.buymeacoffee.com/leoncvlt) to support development of this and [many other projects](https://github.com/leoncvlt?tab=repositories).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleoncvlt%2Fthree-extended-material","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fleoncvlt%2Fthree-extended-material","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleoncvlt%2Fthree-extended-material/lists"}