Extension update: <title>

[Carrotstudio0]

Changes

The Material3D extension for GDevelop is a comprehensive and advanced tool that allows you to change the material properties and visual appearance of 3D objects, whether they are simple cubes or imported models like GLB files. It provides developers with precise control over shading, texturing, and special visual effects like borders and emissive materials.

🎨 Stylized Shading and Toon Look
The extension is crucial for creating highly stylized looks, especially the popular Toon Shading effect:

Toon Shading Combination: The extension provides two specific actions that, when used together, create the full cartoon (cell-shaded) aesthetic:

Make the object toon shaded (MakeToon): This action transforms the object's material to a Toon Shader. It requires a gradient image (e.g., 3 or 5 pixels of different brightness) to define the sharp shading steps, creating the flat, comic-book look.

Add/Change Outline (AddOutline): This action adds a customizable border (outline) around the object. Using the outline in conjunction with the Toon material is highly recommended for achieving a complete cartoon shader effect.

✨ Available Material Styles
In addition to the Toon Shader, the extension supports several other shading models:

Physical Shaded (MakePhysics): This uses the advanced Physically Based Rendering (PBR) model, allowing control over Roughness (0-1), Metalness (0-1), and Specular properties for realistic material simulation.

Emissive (MakeEmissive): Makes the object glow using a specified color and Intensity. It is recommended to pair this with a Bloom post-processing effect.

Wireframe (MakeWireframe / MakeWireframeGLB): Renders the object as a transparent, colored wireframe mesh.

Phong Shaded (MakePhong): Provides the classic shading model with highlights, allowing control over Shininess and Specular color.

Normal / Depth Shaded (MakeNormal / MakeDepth): Utility materials for debugging. MakeNormal displays surface normals, and MakeDepth colors the object based on its proximity to the camera planes.

⚙️ Texture and Effect Control
The extension also offers granular control over textures and blending:

Change Tiling Scale & Offset: Actions to adjust the repetition rate (tiling) and the starting position (offset) of the texture on the X and Y axes.

Normal Texture: Allows adding or changing a Normal Map to a specific face of a 3D object to simulate surface detail and depth.

Change Blend Mode: Sets the material's blending operation (e.g., Normal, Additive, Subtractive, Multiply).

Remove Outline: An action to cleanly remove the fill and outline effects added by AddOutline.

Screen.Recording.2025-12-11.225436.mp4

How to use the new features

---

⚙️ How the Material3D Extension Works (Code Analysis)

The Material3D extension for GDevelop is essentially a wrapper that provides GDevelop events and parameters to manipulate the underlying Three.js 3D rendering properties, primarily focusing on THREE.Material and geometry rendering techniques.

The extension introduces several specialized actions, each designed to modify a specific visual aspect of a 3D object.

1. The Core Mechanic: Material Swapping and Property Setting

Most actions in the extension operate by replacing the existing material of a 3D object with a new type of Three.js material, or by modifying properties on the current material.

• Material Replacement: Actions like MakeToon, MakePhysics, MakePhong, and MakeWireframe create an entirely new material (THREE.MeshToonMaterial, THREE.MeshPhysicalMaterial, etc.) and assign it to the object. Before replacing the material, the code often attempts to preserve the original texture map (threeObject.material.map) if one exists.
• Property Modification: Actions like MakeEmissive and Normal texture often modify the current material's properties (e.g., material.emissiveColor or assigning a normalMap), sometimes requiring an internal conversion to a MeshStandardMaterial if the current material does not support those properties.

2. Implementation of Texture Tiling and Offset

The code provides precise control over texture mapping:

• Tiling Scale: The Change tiling scale action accesses the texture object associated with the material and modifies its repeat property. Critically, it also sets the texture's wrapS and wrapT properties to THREE.RepeatWrapping. This is necessary to ensure the texture repeats visually when the scale is set to a value other than 1.
• Tiling Offset: The Change tiling offset action directly sets the texture's offset property, allowing the texture to be shifted across the object's surface. This can be used to create scrolling or animation effects.

3. Advanced Technique: Outline and Fill Overlays

The AddOutline action is the most complex, relying on creating new geometry and rendering elements:

• Outline Creation: The code first attempts to retrieve existing outline and fill meshes from the original object's userData. If they don't exist, it proceeds to create them.
  • It uses THREE.EdgesGeometry to extract only the non-shared edges of the object's geometry.
  • The outline is rendered using THREE.LineSegments and a basic material (THREE.LineBasicMaterial), allowing control over line color and thickness.
• Fill Overlay: A separate mesh (the fillOverlay) is created using the original geometry and a basic material to control the fill color and opacity behind the outline.
• Render Order: The code explicitly sets the renderOrder of the original object, the fill overlay, and the outline mesh to ensure the elements are drawn in the correct sequence (e.g., fill drawn, then the original object, then the outline) for the effect to appear correctly.
• Removal: The corresponding RemoveOutline action carefully disposes of all these created meshes, materials, and geometries, and resets the original object's renderOrder, preventing memory leaks.

4. Implementation of the Toon Shader

The Make the object toon shaded action achieves the characteristic flat, cartoon look through specific manipulation of the THREE.MeshToonMaterial:

1. Material Instantiation: It creates a new THREE.MeshToonMaterial.
2. Gradient Map Assignment: It loads the user-specified gradient image asset (e.g., a texture with 3-5 distinct color bands). This texture is assigned to the gradientMap property of the Toon Material.
3. Achieving Cell Shading: To create the abrupt, non-smooth shadow transitions that define cell shading, the code sets the texture filtering for the gradient map to THREE.NearestFilter for both minFilter and magFilter. By preventing any texture smoothing (interpolation), the shader is forced to jump sharply between the few colors defined in the gradient map, resulting in the desired comic-book effect.

The full Toon Shader aesthetic is typically achieved by combining this MakeToon action with the AddOutline action for the final border appearance.
https://github.com/user-attachments/assets/50d543fd-3dc2-4fc8-b6d0-6f11a20575fa

Checklist

• I've followed all of the best practices.
• I confirm that this extension can be integrated to this GitHub repository, distributed and MIT licensed.
• I am aware that the extension may be updated by anyone, and do not need my explicit consent to do so.

Example file

My project23.zip

Extension file

Material3De.json

[github-actions]

👋 Hey @Carrotstudio0, thanks for your submission! We are sorry, but the filename of the extension has unrecognized characters. Since filenames with non latin characters ("ASCII") can cause issues, our system won't allow file names with other characters than latin upper- and lowercase characters or numbers. Additionally, the first character must be an uppercase character. Please update your original submission post with a new zip file containing your extension with another file name following those guidelines 🙏

[D8H]

Thank you for submitting an extension.

You agreed to distribute the extension under MIT license but do the main author also agrees with their work being distributed?

[Carrotstudio0]

I think he doesn't agree, so I will add what I have done, and he is only the cartoon shader