feat(mesh): multi-material OBJ rendering

[obiot]

Summary

• OBJ parser now emits groups: Array<{materialName, start, count}> matching the Three.js / glTF convention — every usemtl switch opens a new group slicing the shared index buffer.
• Mesh constructor bakes each material's Kd diffuse color into a per-vertex color buffer at construction time. Vertices on material boundaries are split during parsing so every vertex carries exactly one material's color.
• WebGL & Canvas renderers draw multi-material meshes in a single draw call — per-vertex aColor (WebGL) / per-triangle solid-fill from vertexColors[v0] (Canvas) supplies the right color per face. mesh.tint multiplies on top at render time, so flash / fade / team-color via setTint work exactly as today.
• New Multi-material OBJ example loads four Kenney Space Kit spacecraft (CC0, credited in LICENSE.md), gives each one a team color via mesh.tint, and rotates them in a 2×2 grid.

Single-material meshes are unchanged — same code path, zero new allocations, identical behavior.

Why

melonJS's Mesh previously bound one material per mesh — multi-material OBJs (Kenney packs, Blender exports, anything with painted panels) collapsed to a single uniform color because the parser threw away usemtl boundaries. This change adds proper per-material rendering without giving up the engine's single-draw-call goal.

Implementation notes

• Parser: per-material vertex dedup. Each usemtl resets the active vertexMap so shared (v, vt) pairs across materials get distinct unified-vertex slots — required for per-vertex color baking. Pre-usemtl faces go into an anonymous null-material group so the groups[] contract is always non-empty for non-empty OBJs.
• Mesh: isMultiMaterial gate keeps the existing single-material code path untouched. When triggered, allocates a vertexColors: Uint32Array and fills it by walking each group's index slice. mesh.groups stays exposed for inspection; the per-group tint field is informational under tier 2 (post-construction mutation is a no-op since colors are baked).
• WebGL mesh batcher: new mulPackedARGB helper combines per-vertex baked color with the runtime tint (matches Color.toUint32 packing). Single-material meshes (no vertexColors) take the unchanged fast path.
• Canvas renderer: when vertexColors is present, per-triangle solid-fill reads vertexColors[v0] (all 3 vertices of a triangle share a material color by construction) × currentTint. Single global painter's sort — no inter-group ordering glitches. Per-material textures aren't supported on Canvas (use WebGL for that case).
• MTL parser: dropped the now-obsolete "multiple materials detected — only the first material's texture will be used per mesh" warning, and switched the remaining warnings from the deprecation helper warning() (which formats as "deprecated since version undefined") to plain console.warn.
• Backward compat: single-material OBJs still produce a length-1 groups array so consumers don't need a special case. Existing mesh3d / mesh3dMaterial examples render identically to before.

Test plan

• 8 new parser tests covering single-material default group, multi-usemtl emission, anonymous null-material chunk for pre-usemtl faces, triangulated quads inside groups, winding-fix preserving boundaries, empty OBJ, trailing usemtl with no faces
• All 3565 tests pass (was 3558 → +7 new)
• Existing mesh3d + mesh3dMaterial examples render identically — visually verified
• New multi-material-mesh example renders correctly on both WebGL and Canvas; all 4 ships show distinct per-material colors through the full rotation
• mesh.tint runtime multiplication works on top of baked colors (team colors in the example)
• Local browser FPS measurement (Canvas vs WebGL) — defer; Canvas multi-material is correct but not perf-critical, WebGL is the recommended path

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR adds multi-material support for OBJ meshes by extending the OBJ parser to emit groups[] (per-usemtl index ranges) and updating mesh rendering to support per-vertex baked diffuse colors, plus a new example and expanded test coverage.

Changes:

• OBJ parser now emits groups: Array<{ materialName, start, count }> tracking usemtl boundaries (with an anonymous null group fallback).
• Mesh can bake per-material diffuse (Kd) + opacity into a vertexColors: Uint32Array, and WebGL/Canvas mesh rendering paths use these colors.
• Adds a new “Multi-material OBJ” example (plus Kenney CC0 assets) and new parser tests covering group emission edge cases.

Reviewed changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
packages/melonjs/tests/mesh.spec.js	Adds OBJ parser tests for groups[] emission and boundary edge cases.
packages/melonjs/src/video/webgl/webgl_renderer.js	Updates drawMesh documentation to describe multi-material behavior.
packages/melonjs/src/video/webgl/batchers/mesh_batcher.js	Adds per-vertex color modulation (vertexColors × tint) when present.
packages/melonjs/src/video/canvas/canvas_renderer.js	Adds a solid-fill path for meshes with vertexColors (and 1×1 Kd fallback textures).
packages/melonjs/src/renderable/mesh.js	Adds groups resolution + baked vertexColors, and a 1×1 white-pixel texture fallback.
packages/melonjs/src/loader/parsers/obj.js	Adds usemtl parsing and emits groups[]; resets dedup scope per material.
packages/melonjs/src/loader/parsers/mtl.js	Removes obsolete multi-material warning and switches warnings to console.warn.
packages/examples/src/main.tsx	Registers the new “Multi-material OBJ” example route/entry.
packages/examples/src/examples/multiMaterialMesh/ExampleMultiMaterialMesh.tsx	New example showcasing multi-material OBJ color baking + runtime mesh.tint.
packages/examples/public/assets/multiMaterialMesh/craft_speederB.obj	New Kenney CC0 OBJ asset for the example.
packages/examples/public/assets/multiMaterialMesh/craft_speederB.mtl	New Kenney CC0 MTL asset for the example.
packages/examples/public/assets/multiMaterialMesh/craft_speederA.obj	New Kenney CC0 OBJ asset for the example.
packages/examples/public/assets/multiMaterialMesh/craft_speederA.mtl	New Kenney CC0 MTL asset for the example.
packages/examples/public/assets/multiMaterialMesh/craft_racer.obj	New Kenney CC0 OBJ asset for the example.
packages/examples/public/assets/multiMaterialMesh/craft_racer.mtl	New Kenney CC0 MTL asset for the example.
packages/examples/public/assets/multiMaterialMesh/craft_miner.obj	New Kenney CC0 OBJ asset for the example.
packages/examples/public/assets/multiMaterialMesh/craft_miner.mtl	New Kenney CC0 MTL asset for the example.
packages/examples/LICENSE.md	Adds CC0 credit for the Kenney Space Kit assets used by the new example.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 20 out of 20 changed files in this pull request and generated 8 comments.

Comments suppressed due to low confidence (1)

packages/melonjs/src/video/canvas/canvas_renderer.js:594

• The rawDet === 0 (degenerate UV) fallback path still allocates _meshColorCanvas via document.createElement("canvas"). In worker/OffscreenCanvas contexts (which the earlier solid-fill path now explicitly supports), document is undefined and this will throw. Consider using the same globalThis.OffscreenCanvas-aware allocation approach here as well.

			} else if (rawDet === 0) {
				// degenerate UV triangle — sample a solid color from the texture
				// (common with color-palette models where all 3 UVs map to the same point)
				context.closePath();
				if (!this._meshColorCanvas) {
					this._meshColorCanvas = document.createElement("canvas");
					this._meshColorCanvas.width = 1;
					this._meshColorCanvas.height = 1;
					this._meshColorCtx = this._meshColorCanvas.getContext("2d");
				}

[Copilot]

Pull request overview

Copilot reviewed 23 out of 23 changed files in this pull request and generated 7 comments.

[Copilot]

Pull request overview

Copilot reviewed 23 out of 23 changed files in this pull request and generated 7 comments.