Reapply "Feat/plugin support, allow third_party feat(spine) to create plugin f…" (#403) (#424)

This reverts commit 5bcfb9fa04.
This commit is contained in:
hyde zhou
2026-11-16 16:33:05 +08:00
committed by GitHub
parent 1df519e248
commit 6ccf1cf9a8
14 changed files with 1222 additions and 8 deletions
+32
View File
@@ -3205,6 +3205,38 @@ request fullscreen is not supported on this platform.
exit fullscreen is not supported on this platform. exit fullscreen is not supported on this platform.
### 9010
UIMesh.setMeshData: unsupported vertexStride %d, expected %d (V3F_T2F_C4B) or %d (V3F_T2F_C4B_C4B); data rejected.
### 9011
UIMesh.setMeshData: negative counts (vertexCount %d, indexCount %d); data rejected.
### 9012
UIMesh.setMeshData: vertexData holds %d bytes, but %d vertices x %d bytes are declared; data rejected.
### 9013
UIMesh.setMeshData: indexData is %d bytes at offset %d, but %d Uint16 indices need %d bytes (2-byte aligned view); data rejected.
### 9014
UIMesh.setMeshData: indices[%d] = %d is out of range for %d vertices; data rejected.
### 9015
UIMesh.setMeshData: segment %d range [%d, %d) is out of bounds for indexCount %d; data rejected.
### 9016
UIMesh.setMeshData: %d vertices / %d indices exceed the accessor cap (%d / %d); split the mesh. Data rejected.
### 9017
UIMesh: render data allocation failed for %d vertices / %d indices (accessor cap: %d / %d).
### 9100 ### 9100
texture size exceeds current device limits %d/%d texture size exceeds current device limits %d/%d
+3
View File
@@ -307,6 +307,9 @@
"worker-pool": { "worker-pool": {
"modules": ["worker", "worker-pool"], "modules": ["worker", "worker-pool"],
"dependentModules": ["worker"] "dependentModules": ["worker"]
},
"webassembly": {
"modules": ["webassembly"]
} }
}, },
"moduleOverrides": [{ "moduleOverrides": [{
+1
View File
@@ -25,6 +25,7 @@
export * from './label'; export * from './label';
export { Sprite } from './sprite'; export { Sprite } from './sprite';
export { UIMeshRenderer } from './ui-mesh-renderer'; export { UIMeshRenderer } from './ui-mesh-renderer';
export * from './ui-mesh';
export { LabelOutline } from './label-outline'; export { LabelOutline } from './label-outline';
export { UIStaticBatch } from './ui-static-batch'; export { UIStaticBatch } from './ui-static-batch';
export { LabelShadow } from './label-shadow'; export { LabelShadow } from './label-shadow';
+636
View File
@@ -0,0 +1,636 @@
/*
Copyright (c) 2026
Generic 2D mesh data consumer: the plugin feeds pre-baked vertex/index/segment
data through setMeshData; this component owns buffer allocation, batching and
submission through the 2D batcher, so extensions can render custom meshes
without touching engine internals.
Vertices are ALWAYS node-local; UIMesh owns the node transform:
* not batched -- on the GPU, via USE_LOCAL + the per-draw cc-local UBO the
batcher already maintains for middleware draws;
* batched -- the FULL world matrix baked into the chunk copy on the CPU
(a merged batch carries no per-draw matrix), matching the GPU path, z /
X-Y rotation included.
USE_LOCAL / setUseLocal are derived internally; there is no world-baked
input mode.
Data is FillColorType.VERTEX, so the batcher applies no cascaded opacity:
UIMesh folds it into the copied vertices itself, accumulated as Batcher2D.walk
does for COLOR data (own color alpha x, per ancestor, UIOpacity localOpacity x
that ancestor's color alpha). `premultipliedAlpha` declares the data format:
alpha-byte-only vs RGBA + dark RGB fading.
The batcher resets the shared index tail after every upload (vertex bytes
survive), so indices are re-submitted EVERY frame (appendIndexBuffer) and only
the vertex refresh is _vertexDirty-gated. A dirty-gated submission would leave
a static mesh's draw range aliasing whichever sibling appends after the reset
(two UIMeshes in one buffer, one paused: it would draw the other's triangles).
*/
import { JSB } from 'internal:constants';
import { ccclass, editable, serializable } from 'cc.decorator';
import { errorID } from '../../core';
import { Mat4 } from '../../core/math';
import { UIRenderer } from '../framework/ui-renderer';
import { RenderData } from '../renderer/render-data';
import { RenderDrawInfo, RenderDrawInfoType } from '../renderer/render-draw-info';
import { StaticVBAccessor } from '../renderer/static-vb-accessor';
import type { Batcher2D } from '../renderer/batcher-2d';
import { vfmtPosUvColor4B, vfmtPosUvTwoColor4B, getAttributeStride } from '../renderer/vertex-format';
import { RenderEntity, RenderEntityType } from '../renderer/render-entity';
import { director, DirectorEvent } from '../../game';
import { Texture2D } from '../../asset/assets';
import { builtinResMgr } from '../../asset/asset-manager';
import { BlendFactor } from '../../gfx';
import type { MeshBuffer } from '../renderer/mesh-buffer';
import type { MaterialInstance } from '../../render-scene';
import type { Material } from '../../asset/assets/material';
import type { Node } from '../../scene-graph';
/**
* @en A segment of the mesh: a range of indices drawn with one texture+material.
* @zh 网格的一个片段:一段索引,用同一纹理+材质绘制。
*/
export interface UIMeshSegment {
indexOffset: number;
indexCount: number;
texture: Texture2D | null;
material: MaterialInstance | null;
}
/**
* @en Pre-baked mesh data for one frame.
* @zh 一帧的预烘焙网格数据。
* vertexStride: 24 (single-color V3F_T2F_C4B) or 28 (two-color V3F_T2F_C4B_C4B).
*/
export interface UIMeshData {
vertexCount: number;
vertexStride: number;
vertexData: Uint8Array;
indexCount: number;
indexData: Uint8Array;
segments: UIMeshSegment[];
}
// Shared static vertex-buffer accessors, keyed by the current Batcher2D: it
// destroys every accessor registered with it, so a rebuilt root must never
// reuse a cached (destroyed) accessor, and each new one must be registered
// with the current batcher or its buffers would never be uploaded or reset.
let _accessorBatcher: Batcher2D | null = null;
let _sharedAccessor: StaticVBAccessor | null = null;
let _sharedTintAccessor: StaticVBAccessor | null = null;
// Registration keys in the batcher's accessor map (base-36 namespaced, the
// same convention as the built-in middleware assemblers — spine/dragon-bones).
const UIMESH_ACCESSOR_KEY = Number.parseInt('UIMESH', 36);
const UIMESH_TINT_ACCESSOR_KEY = Number.parseInt('UIMESHTINT', 36);
// The two consumed vertex formats (24 / 28 bytes); strides derived from the
// definitions so the byte math always matches the chunk's format.
const MESH_STRIDE_BYTES = getAttributeStride(vfmtPosUvColor4B);
const MESH_STRIDE_TINT_BYTES = getAttributeStride(vfmtPosUvTwoColor4B);
/**
* @en A generic 2D mesh renderer that consumes pre-baked vertex/index data.
* The data provider (e.g. a spine plugin) fills setMeshData every frame; this
* component handles buffer allocation, batching and submission.
* @zh 通用 2D 网格渲染器,消费预烘焙的顶点/索引数据。数据提供方(如 spine 插件)
* 每帧调用 setMeshData,本组件负责缓冲分配、合批与提交。
*/
@ccclass('cc.UIMesh')
export class UIMesh extends UIRenderer {
@serializable
protected _enableBatch = false;
/**
* @en Whether the incoming color data is premultiplied-alpha. Declares how
* cascaded opacity is folded into the vertices (alpha byte only vs
* RGBA + dark RGB) and the blend factors of the builtin material.
* @zh 输入颜色数据是否为预乘 alpha 格式。决定级联不透明度折算方式
* (仅 alpha 字节 vs RGBA + dark RGB)及内置材质混合因子。
*/
@serializable
protected _premultipliedAlpha = false;
protected _meshData: UIMeshData | null = null;
protected _useTint = false;
private _drawInfoList: RenderDrawInfo[] = [];
// Poll cache (see _onBeforeDraw): inputs captured by the last
// updateVertexBuffer run; drift means the baked transform / folded opacity
// no longer match. The full matrix is tracked — the bake applies all of it.
private _pollOpacity = 1;
private _pollWorldMatrix = new Mat4();
// Vertex-staleness latch, consumed by _onBeforeDraw to pick a full refresh
// vs an index-only resubmit. Starts dirty so the first frame prepares.
private _vertexDirty = true;
constructor () {
super();
this._useVertexOpacity = true;
}
/**
* @en Feeds the pre-baked mesh data for the current frame.
* @zh 喂入当前帧的预烘焙网格数据。
*/
public setMeshData (data: UIMeshData): void {
// Reject bad input at the call site; a rejected frame keeps the last
// accepted mesh.
if (!this._validateMeshData(data)) return;
const useTint = data.vertexStride === MESH_STRIDE_TINT_BYTES;
if (useTint !== this._useTint) {
this.destroyRenderData();
this._useTint = useTint;
this._flushAssembler();
// The builtin fallback material follows the stride (TWO_COLORED).
this.updateMaterial();
}
this._meshData = data;
this._vertexDirty = true;
}
private _validateMeshData (data: UIMeshData): boolean {
const vc = data.vertexCount;
const ic = data.indexCount;
if (data.vertexStride !== MESH_STRIDE_BYTES && data.vertexStride !== MESH_STRIDE_TINT_BYTES) {
errorID(9010, data.vertexStride, MESH_STRIDE_BYTES, MESH_STRIDE_TINT_BYTES);
return false;
}
if (vc < 0 || ic < 0) {
errorID(9011, vc, ic);
return false;
}
// Capacity limits come from the accessor that will serve the data.
const accessor = this.ensureAccessor(data.vertexStride === MESH_STRIDE_TINT_BYTES);
if (vc > accessor.maxVertexCount || ic > accessor.maxIndexCount) {
errorID(9016, vc, ic, accessor.maxVertexCount, accessor.maxIndexCount);
return false;
}
if (!data.vertexData || data.vertexData.byteLength < vc * data.vertexStride) {
errorID(9012, data.vertexData ? data.vertexData.byteLength : 0, vc, data.vertexStride);
return false;
}
if (!data.indexData || data.indexData.byteOffset % 2 !== 0 || data.indexData.byteLength < ic * 2) {
errorID(
9013,
data.indexData ? data.indexData.byteLength : 0,
data.indexData ? data.indexData.byteOffset : 0,
ic,
ic * 2,
);
return false;
}
// Indices are mesh-local; anything >= vertexCount would sample vertices
// of other chunks in the shared buffer (silent geometry corruption).
const indices = new Uint16Array(data.indexData.buffer, data.indexData.byteOffset, ic);
for (let i = 0; i < ic; ++i) {
if (indices[i] >= vc) {
errorID(9014, i, indices[i], vc);
return false;
}
}
for (let i = 0; i < data.segments.length; ++i) {
const seg = data.segments[i];
if (seg.indexOffset < 0 || seg.indexCount < 0 || seg.indexOffset + seg.indexCount > ic) {
errorID(9015, i, seg.indexOffset, seg.indexOffset + seg.indexCount, ic);
return false;
}
}
return true;
}
/**
* @en Whether to enable sprite batching.
* @zh 是否启用合批。
*/
@editable
get enableBatch (): boolean { return this._enableBatch; }
set enableBatch (value: boolean) {
this._enableBatch = value;
this._syncTransformMode();
this.updateMaterial();
}
/**
* @en Whether the input color data is premultiplied-alpha.
* @zh 输入颜色数据是否为预乘 alpha 格式。
*/
@editable
get premultipliedAlpha (): boolean { return this._premultipliedAlpha; }
set premultipliedAlpha (value: boolean) {
this._premultipliedAlpha = value;
this.updateMaterial();
this._vertexDirty = true;
this.onPremultipliedAlphaChanged();
}
/**
* Notifies subclasses the declared format changed. The property is owned
* here (single source of truth); producers override this to forward it to
* their baker instead of redeclaring the field.
*/
protected onPremultipliedAlphaChanged (): void {}
public onLoad (): void {
super.onLoad();
// Deserialization has applied _enableBatch by now; re-derive the
// legacy switch state.
this._syncTransformMode();
}
/**
* useLocal == "vertices are still node-local at submit time". Batched data
* is world-baked by updateVertexBuffer before submit, and native
* middleware draws only merge when !useLocal — hence !enableBatch.
*/
private _syncTransformMode (): void {
this._renderEntity.setUseLocal(!this._enableBatch);
this._vertexDirty = true;
}
protected _updateColor (): void {
super._updateColor();
// The opacity fold in updateVertexBuffer reads this._color, so a
// change must re-prepare. Visibility (color.a 0 <-> !0) is recomputed
// fresh by _onBeforeDraw.
this._vertexDirty = true;
}
protected _onMaterialModified (idx: number, material: Material | null): void {
super._onMaterialModified(idx, material);
// Draw infos cache the material reference; a swap must rebuild them.
// The base mark only re-syncs visibility (no updateRenderer override
// anymore), and the passDirty self-heal path needs an assembler.
this._vertexDirty = true;
}
public onEnable (): void {
super.onEnable();
// BEFORE_DRAW fires between the update and render phases, outside the
// director.pause() gate — the render loop still redraws (and resets
// shared buffers) while paused, so submission must keep running.
if (JSB) director.on(DirectorEvent.BEFORE_DRAW, this._onBeforeDraw, this);
}
public onDisable (): void {
if (JSB) director.off(DirectorEvent.BEFORE_DRAW, this._onBeforeDraw, this);
super.onDisable();
}
/**
* JSB per-frame driver (director BEFORE_DRAW); web is driven by fillBuffers
* instead. Three jobs:
* * poll — transforms / UIOpacity never mark a middleware renderer, so
* compare the live values against the last updateVertexBuffer capture;
* * visibility — recomputed fresh (the base class' synchronous
* _updateColor recompute is assembler-gated, dead here); an invisible
* mesh submits nothing and its draw infos are cleared;
* * data — full refresh when the latch is set or the mesh just became
* visible again, else the frame-scoped appendIndexBuffer only.
*/
private _onBeforeDraw (): void {
if (!JSB || !this._renderData || !this._meshData) return;
if (this._enableBatch && !this.node.worldMatrix.strictEquals(this._pollWorldMatrix)) {
this._vertexDirty = true;
}
if (this._computeCascadedOpacity() !== this._pollOpacity) {
this._vertexDirty = true;
}
const wasRenderable = this._renderFlag;
const canRender = this._canRender();
this._renderFlag = canRender;
this._renderEntity.enabled = canRender;
if (!canRender) {
if (wasRenderable) this._renderEntity.clearDynamicRenderDrawInfos();
return;
}
if (this._vertexDirty || !wasRenderable) {
this._prepareNativeDrawInfos();
this._vertexDirty = false;
} else {
this.appendIndexBuffer();
}
}
protected _flushAssembler (): void {
if (this._renderData === null) {
const accessor = this.ensureAccessor(this._useTint);
this._renderData = RenderData.add(this._useTint ? vfmtPosUvTwoColor4B : vfmtPosUvColor4B, accessor);
}
}
protected _render (batcher: any): void {
const prepared = this._prepareBuffers();
if (!prepared || !this._meshData) return;
const { meshBuffer, startIndex } = prepared;
const data = this._meshData;
// Segments without their own material fall back to the component
// material (the builtin spine effect).
for (const seg of data.segments) {
const mat = seg.material || this.getRenderMaterial(0);
if (seg.texture && mat) {
batcher.commitMiddleware(
this,
meshBuffer,
startIndex + seg.indexOffset,
seg.indexCount,
seg.texture,
mat,
this._enableBatch,
);
}
}
}
private _prepareBuffers (): { meshBuffer: MeshBuffer, startIndex: number } | null {
// Full refresh: the dirty-gated vertex half + the frame-scoped index
// half. Shared by the web walk (_render) and _prepareNativeDrawInfos.
if (!this.updateVertexBuffer()) return null;
return this.appendIndexBuffer();
}
/**
* Vertex half of a refresh: grow the chunk, copy this frame's bytes, bake
* the world matrix when batching, fold cascaded opacity, capture the poll
* inputs. The expensive half — callers gate it (native: dirty only; web:
* every frame). Returns whether the chunk holds this frame's vertices.
*/
protected updateVertexBuffer (): boolean {
if (!this._renderData || !this._meshData) return false;
const data = this._meshData;
const rd = this._renderData;
const vc = data.vertexCount;
const ic = data.indexCount;
if (vc < 1 || ic < 1) return false;
const vLength = vc * data.vertexStride;
// ~10% head room, clamped to the accessor's per-chunk caps — an
// unclamped reserve would permanently fail data that fits (30000 ->
// 33000 requested > 32767). Per-frame counts live on the render data;
// the reserve lives on the chunk.
if (!rd.chunk || rd.chunk.vb.byteLength < vLength || rd.chunk.indexCount < ic) {
rd.resize(
Math.min(Math.ceil(vc * 1.1), rd.accessor.maxVertexCount),
Math.min(Math.ceil(ic * 1.1), rd.accessor.maxIndexCount),
);
if (!rd.chunk) {
errorID(9017, vc, ic, rd.accessor.maxVertexCount, rd.accessor.maxIndexCount);
return false;
}
rd.updateSize(vc, ic);
} else if (rd.vertexCount !== vc || rd.indexCount !== ic) {
rd.updateSize(vc, ic);
}
if (!rd.chunk) return false;
// Copy into the chunk's view of the shared vData.
const vbuf = rd.chunk.vb;
const vU8 = new Uint8Array(vbuf.buffer, vbuf.byteOffset, vLength);
vU8.set(data.vertexData.subarray(0, vLength));
// Batched: a merged batch carries no per-draw matrix, so bake the
// world transform into the chunk copy (the incoming vertexData may be
// a worker-shared view — never touch it).
if (this._enableBatch) {
this._bakeWorldTransform(vbuf, vLength, data.vertexStride);
}
// Cascaded opacity: VERTEX-type data gets no engine-side fade, UIMesh
// applies it while copying (see the opacity contract in the header).
const opacity = this._computeCascadedOpacity();
if (opacity < 0.9999) {
this._applyOpacity(vU8, vc, data.vertexStride, opacity);
}
// Capture the poll inputs (compared in _onBeforeDraw).
this._pollOpacity = opacity;
if (this._enableBatch) {
this._pollWorldMatrix.set(this.node.worldMatrix);
}
return true;
}
/**
* Index half: offset by the chunk's vertexOffset, append into the shared
* index buffer, refresh the draw-info offsets. Must run EVERY frame for
* every participating mesh — the batcher resets the index tail after each
* upload while draw infos keep absolute offsets, so a mesh that skipped
* would alias whichever sibling appends first (see the header contract).
* Runs exactly once per frame (native pump / web fillBuffers);
* commitMiddleware reads meshBuffer.iData.
*/
protected appendIndexBuffer (): { meshBuffer: MeshBuffer, startIndex: number } | null {
const data = this._meshData;
const rd = this._renderData;
if (!rd || !rd.chunk || !data || data.vertexCount < 1 || data.indexCount < 1) {
return null;
}
const meshBuffer = rd.getMeshBuffer()!;
// The native batcher resets indexOffset through shared memory after
// uploading — sync the JS-side cache before appending.
if (JSB) meshBuffer.indexOffset = meshBuffer.sharedBuffer[2];
const startIndex = meshBuffer.indexOffset;
const ic = data.indexCount;
const chunkOffset = rd.chunk.vertexOffset;
const offsetIndices = new Uint16Array(ic);
new Uint8Array(offsetIndices.buffer).set(data.indexData.subarray(0, ic * 2));
for (let i = 0; i < ic; i++) offsetIndices[i] += chunkOffset;
rd.chunk.vertexAccessor.appendIndices(rd.chunk.bufferId, offsetIndices);
rd.chunk.vertexAccessor.getMeshBuffer(rd.chunk.bufferId).setDirty();
// Static frames never re-run _prepareNativeDrawInfos — keep the cached
// draw infos' offsets in step (segment mapping mirrors it).
this._refreshDrawInfoOffsets(startIndex);
return { meshBuffer, startIndex };
}
private _refreshDrawInfoOffsets (startIndex: number): void {
const data = this._meshData;
if (!data || this._drawInfoList.length === 0) return;
let drawIndex = 0;
for (const seg of data.segments) {
const mat = seg.material || this.getRenderMaterial(0);
if (!seg.texture || !mat) continue;
const drawInfo = this._drawInfoList[drawIndex++];
if (drawInfo) drawInfo.setIndexOffset(startIndex + seg.indexOffset);
}
}
/**
* Bakes the FULL world matrix into the chunk copy's positions — exactly
* what the USE_LOCAL GPU path applies (pos = cc_matWorld * pos), z and
* X/Y-rotation included, so batched and unbatched renders agree. Identity
* is skipped.
*/
private _bakeWorldTransform (vbuf: Float32Array, byteLength: number, stride: number): void {
const m = this.node.worldMatrix;
const m00 = m.m00; const m01 = m.m01; const m02 = m.m02;
const m04 = m.m04; const m05 = m.m05; const m06 = m.m06;
const m08 = m.m08; const m09 = m.m09; const m10 = m.m10;
const m12 = m.m12; const m13 = m.m13; const m14 = m.m14;
if (m00 === 1 && m01 === 0 && m02 === 0
&& m04 === 0 && m05 === 1 && m06 === 0
&& m08 === 0 && m09 === 0 && m10 === 1
&& m12 === 0 && m13 === 0 && m14 === 0) return;
const floats = new Float32Array(vbuf.buffer, vbuf.byteOffset, byteLength >> 2);
const strideF = stride >> 2;
const vertexCount = byteLength / stride;
for (let i = 0; i < vertexCount; i++) {
const o = i * strideF;
const x = floats[o];
const y = floats[o + 1];
const z = floats[o + 2];
floats[o] = m00 * x + m04 * y + m08 * z + m12;
floats[o + 1] = m01 * x + m05 * y + m09 * z + m13;
floats[o + 2] = m02 * x + m06 * y + m10 * z + m14;
}
}
/**
* Cascaded opacity as Batcher2D.walk accumulates it for COLOR data: own
* color alpha x, per ancestor, localOpacity x that ancestor's color alpha.
*/
private _computeCascadedOpacity (): number {
let opacity = this._color.a / 255;
for (let node: Node | null = this.node; node; node = node.parent) {
opacity *= node._uiProps.localOpacity;
if (node !== this.node) {
const ancestor = node._uiProps.uiComp as UIRenderer | null;
if (ancestor && ancestor.color) opacity *= ancestor.color.a / 255;
}
}
return opacity;
}
/**
* Folds opacity into the copied vertices. Light color sits at bytes
* 20..23 (pos*3f + uv*2f), dark at 24..27 for two-color. Straight data
* fades via the alpha byte only; PMA data scales light RGBA + dark RGB
* (dark alpha is the sentinel, not a fade channel).
*/
private _applyOpacity (vU8: Uint8Array, vc: number, stride: number, opacity: number): void {
const pma = this._premultipliedAlpha;
const darkRGB = (pma && stride === MESH_STRIDE_TINT_BYTES) ? 3 : 0;
for (let i = 0; i < vc; i++) {
const o = i * stride + 20;
if (pma) {
vU8[o] = (vU8[o] * opacity + 0.5) | 0;
vU8[o + 1] = (vU8[o + 1] * opacity + 0.5) | 0;
vU8[o + 2] = (vU8[o + 2] * opacity + 0.5) | 0;
}
vU8[o + 3] = (vU8[o + 3] * opacity + 0.5) | 0;
for (let j = 0; j < darkRGB; j++) {
vU8[o + 4 + j] = (vU8[o + 4 + j] * opacity + 0.5) | 0;
}
}
}
private _prepareNativeDrawInfos (): void {
this._renderEntity.clearDynamicRenderDrawInfos();
// Vertex refresh + this frame's index submission; a null return means
// there is nothing drawable this frame.
const prepared = this._prepareBuffers();
const data = this._meshData;
const rd = this._renderData;
if (!prepared || !data || !rd?.chunk) return;
const { startIndex } = prepared;
let drawIndex = 0;
for (const seg of data.segments) {
const mat = seg.material || this.getRenderMaterial(0);
if (!seg.texture || !mat) continue;
let drawInfo = this._drawInfoList[drawIndex];
if (!drawInfo) {
drawInfo = new RenderDrawInfo();
drawInfo.setDrawInfoType(RenderDrawInfoType.MIDDLEWARE);
this._drawInfoList[drawIndex] = drawInfo;
}
drawInfo.setAccAndBuffer(rd.accessor.id, rd.chunk.bufferId);
drawInfo.setIndexOffset(startIndex + seg.indexOffset);
drawInfo.setIBCount(seg.indexCount);
drawInfo.setTexture(seg.texture.getGFXTexture());
drawInfo.setSampler(seg.texture.getGFXSampler());
drawInfo.setMaterial(mat);
this._renderEntity.setDynamicRenderDrawInfo(drawInfo, drawIndex);
drawIndex++;
}
}
/**
* The spine effect (default-spine-material): ui-sprite-material has no
* USE_LOCAL variant — node-local input through it would render stuck at
* the origin.
*/
protected _updateBuiltinMaterial (): Material {
return builtinResMgr.get<Material>('default-spine-material');
}
/**
* Keeps the builtin material instance in step with the declared vertex
* space / data format: USE_LOCAL for the GPU take-over mode, TWO_COLORED
* for two-color data, and blend factors matching the alpha format.
*/
public updateMaterial (): void {
// Align the legacy blend-factor fields first so _updateBlendFunc
// (inside super) never fights the explicit patching below.
this._srcBlendFactor = this._premultipliedAlpha ? BlendFactor.ONE : BlendFactor.SRC_ALPHA;
this._dstBlendFactor = BlendFactor.ONE_MINUS_SRC_ALPHA;
super.updateMaterial();
if (this._customMaterial) return; // custom materials are the user's contract
const inst = this.getMaterialInstance(0);
if (!inst) return;
inst.recompileShaders({
USE_LOCAL: !this._enableBatch,
TWO_COLORED: this._useTint,
});
// Straight data: src_alpha / 1-src_alpha (the effect default);
// premultiplied data: ONE / 1-src_alpha, color and alpha channels.
const src = this._premultipliedAlpha ? BlendFactor.ONE : BlendFactor.SRC_ALPHA;
const pass = inst.passes[0];
const target = pass.blendState.targets[0];
target.blend = true;
target.blendSrc = src;
target.blendSrcAlpha = src;
target.blendDst = BlendFactor.ONE_MINUS_SRC_ALPHA;
target.blendDstAlpha = BlendFactor.ONE_MINUS_SRC_ALPHA;
pass.blendState.setTarget(0, target);
pass._updatePassHash();
}
protected createRenderEntity (): RenderEntity {
const entity = new RenderEntity(RenderEntityType.DYNAMIC);
// useLocal is re-derived in _syncTransformMode once deserialization
// has run.
entity.setUseLocal(!this._enableBatch);
return entity;
}
private ensureAccessor (useTint: boolean): StaticVBAccessor {
const batcher = director.root!.batcher2D;
// The previous batcher destroyed its accessors — invalidate the cache.
if (_accessorBatcher !== batcher) {
_accessorBatcher = batcher;
_sharedAccessor = null;
_sharedTintAccessor = null;
}
let accessor = useTint ? _sharedTintAccessor : _sharedAccessor;
if (!accessor) {
const device = director.root!.device;
// Copy the format: the accessor empties its attributes array on
// destroy, and the vfmt* constants are shared module-level state.
const attributes = (useTint ? vfmtPosUvTwoColor4B : vfmtPosUvColor4B).slice();
// 32767: the spine middleware assembler's per-chunk cap
// (cocos/spine/assembler/simple.ts), half the Uint16 index space.
accessor = new StaticVBAccessor(device, attributes, 32767);
batcher.registerBufferAccessor(useTint ? UIMESH_TINT_ACCESSOR_KEY : UIMESH_ACCESSOR_KEY, accessor);
if (useTint) {
_sharedTintAccessor = accessor;
} else {
_sharedAccessor = accessor;
}
}
return accessor;
}
}
+6
View File
@@ -85,6 +85,12 @@ export class StaticVBAccessor extends BufferAccessor {
private _id = 0; private _id = 0;
get id (): number { return this._id; } get id (): number { return this._id; }
/** Per-chunk capacity; allocateChunk refuses requests above these. */
get maxVertexCount (): number { return this._vCount; }
/** Per-chunk index capacity; allocateChunk refuses requests above these. */
get maxIndexCount (): number { return this._iCount; }
public constructor (device: Device, attributes: Attribute[], vCount?: number, iCount?: number) { public constructor (device: Device, attributes: Attribute[], vCount?: number, iCount?: number) {
super(device, attributes); super(device, attributes);
this._vCount = vCount || Math.floor(macro.BATCHER2D_MEM_INCREMENT * 1024 / this._vertexFormatBytes); this._vCount = vCount || Math.floor(macro.BATCHER2D_MEM_INCREMENT * 1024 / this._vertexFormatBytes);
+8 -1
View File
@@ -412,7 +412,7 @@
"spine-3.8": { "spine-3.8": {
"enginePlugin": true, "enginePlugin": true,
"cmakeConfig": "USE_SPINE_3_8", "cmakeConfig": "USE_SPINE_3_8",
"default": true, "default": false,
"isNativeModule": true, "isNativeModule": true,
"label": "i18n:ENGINE.features.spine_38.label", "label": "i18n:ENGINE.features.spine_38.label",
"description": "i18n:ENGINE.features.spine_38.description", "description": "i18n:ENGINE.features.spine_38.description",
@@ -504,6 +504,13 @@
"description": "i18n:ENGINE.features.xr.description", "description": "i18n:ENGINE.features.xr.description",
"enginePlugin": false, "enginePlugin": false,
"envCondition": "$NATIVE || $HTML5" "envCondition": "$NATIVE || $HTML5"
},
"webassembly": {
"default": true,
"required": true,
"label": "WebAssembly",
"description": "Export the engine's cross-platform WebAssembly loading interface as cc.wasm, so that extensions and game scripts can load their own .wasm files. 以 cc.wasm 导出引擎的跨平台 WebAssembly 加载接口,供扩展与游戏脚本加载自己的 .wasm 文件。",
"enginePlugin": true
} }
}, },
"categories": { "categories": {
@@ -42,7 +42,7 @@ function formatValue(value) {
} }
const imageExt = ['.png', '.jpg', '.jpeg', '.webp', '.gif']; const imageExt = ['.png', '.jpg', '.jpeg', '.webp', '.gif'];
const pageAttr = ['name', 'size', 'format', 'filter', 'repeat', 'pma']; const pageAttr = ['name', 'size', 'format', 'filter', 'repeat', 'scale', 'pma'];
class ParseAtlasFile { class ParseAtlasFile {
constructor() { } constructor() { }
+52
View File
@@ -0,0 +1,52 @@
/*
Copyright (c) 2026 Xiamen Yaji Software Co., Ltd.
https://www.cocos.com/
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is furnished
to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
*/
import { instantiateWasm, fetchBuffer, fetchUrl, ensureWasmModuleReady } from 'pal/wasm';
/**
* @en
* The engine's packaged cross-platform WebAssembly interface (pal/wasm).
*
* Re-exported under the public `cc.wasm` namespace so extension/game code can
* load its own `.wasm` files through the same platform-adaptive path the engine
* uses internally for box2d / physx / spine / webgpu:
*
* - web: fetch the `.wasm` bytes, then `WebAssembly.instantiate`;
* - mini-game: resolve the path into `cocos-js/` and delegate to the platform's
* `CCWebAssembly.instantiate` (which accepts a file path, never
* raw bytes — this is why embedded-base64 wasm fails there);
* - native: read the file from `src/cocos-js/` via `fileUtils`.
*
* The `wasmUrl` argument is a bare file name (e.g. `'foo.wasm'`) whose file is
* expected to land in the build output's `cocos-js/` directory.
* @zh
* 引擎封装好的跨平台 WebAssembly 接口(pal/wasm),通过 `cc.wasm` 命名空间公开,
* 供扩展/游戏代码用与引擎内部一致的路径加载自己的 `.wasm`。
*/
export const wasm = {
instantiateWasm,
fetchBuffer,
fetchUrl,
ensureWasmModuleReady,
};
@@ -43,6 +43,19 @@ set(USE_DEBUG_RENDERER OFF)
include(${cocosdir}/CMakeLists.txt) include(${cocosdir}/CMakeLists.txt)
include(${cocosdir}/tools/simulator/libsimulator/CMakeLists.txt) include(${cocosdir}/tools/simulator/libsimulator/CMakeLists.txt)
# Native plugin discovery, same mechanism as native builds. Opt-in: pass
# -DSIMULATOR_PLUGIN_SCAN_DIRS="<dir>[;<dir>]" with directories to scan for
# cc_plugin.json. Unset (default) keeps the stock plugin-less simulator.
set(SIMULATOR_PLUGIN_SCAN_DIRS "" CACHE STRING
"Directories scanned for cc_plugin.json native plugins")
set(COCOS_X_PATH ${cocosdir})
if(SIMULATOR_PLUGIN_SCAN_DIRS)
set(CC_PROJECT_DIR ${CMAKE_BINARY_DIR}/plugin-scan)
set(CC_PLUGIN_PATH ${SIMULATOR_PLUGIN_SCAN_DIRS})
file(MAKE_DIRECTORY ${CC_PROJECT_DIR})
cc_common_before_target(${APP_NAME})
endif()
if(MACOSX) if(MACOSX)
@@ -153,6 +166,11 @@ else()
endif() endif()
target_link_libraries(${LIB_NAME} ${ENGINE_NAME} simulator) target_link_libraries(${LIB_NAME} ${ENGINE_NAME} simulator)
# Plain signature, matching the call above: mixing keyword/plain forms for one
# target is a hard CMake error.
if(TARGET plugin_registry)
target_link_libraries(${LIB_NAME} plugin_registry)
endif()
target_include_directories(${LIB_NAME} PRIVATE target_include_directories(${LIB_NAME} PRIVATE
Classes Classes
) )
@@ -25,6 +25,7 @@
#include "Game.h" #include "Game.h"
#include "cocos/application/ApplicationManager.h" #include "cocos/application/ApplicationManager.h"
#include "cocos/bindings/jswrapper/SeApi.h" #include "cocos/bindings/jswrapper/SeApi.h"
#include "cocos/plugins/Plugins.h"
#include "cocos/bindings/manual/jsb_classtype.h" #include "cocos/bindings/manual/jsb_classtype.h"
#include "cocos/bindings/manual/jsb_global.h" #include "cocos/bindings/manual/jsb_global.h"
#include "cocos/bindings/manual/jsb_module_register.h" #include "cocos/bindings/manual/jsb_module_register.h"
@@ -56,6 +57,8 @@ Game::~Game() {
int Game::init() { int Game::init() {
cc::pipeline::GlobalDSManager::setDescriptorSetLayout(); cc::pipeline::GlobalDSManager::setDescriptorSetLayout();
// Mirrors BaseGame::init(): register native plugins before any script runs.
cc_load_all_plugins();
SimulatorApp::getInstance()->init(); SimulatorApp::getInstance()->init();
std::call_once(_windowCreateFlag, [&]() { std::call_once(_windowCreateFlag, [&]() {
cc::ISystemWindowInfo info; cc::ISystemWindowInfo info;
@@ -30,6 +30,11 @@
/* protobuf config.h for MSVC. On other platforms, this is generated /* protobuf config.h for MSVC. On other platforms, this is generated
* automatically by autoheader / autoconf / configure. */ * automatically by autoheader / autoconf / configure. */
/* VS 18 (MSVC >= 1950) removed the legacy <hash_map>/<hash_set> headers.
* Leave the HAVE_* flags undefined there so stubs/hash.h takes its built-in
* MISSING_HASH fallback (std::map / std::set based). */
#if !(defined(_MSC_VER) && _MSC_VER >= 1950)
/* the location of <hash_map> */ /* the location of <hash_map> */
#define HASH_MAP_H <hash_map> #define HASH_MAP_H <hash_map>
@@ -53,6 +58,8 @@
/* define if the compiler has hash_set */ /* define if the compiler has hash_set */
#define HAVE_HASH_SET 1 #define HAVE_HASH_SET 1
#endif // MSVC >= 1950
/* define if you want to use zlib. See readme.txt for additional /* define if you want to use zlib. See readme.txt for additional
* requirements. */ * requirements. */
// #define HAVE_ZLIB 1 // #define HAVE_ZLIB 1
+7 -1
View File
@@ -78,9 +78,15 @@ async function bundleRuntimeAdapter () {
const platforms = getPlatformsFromPath(platformsPath); const platforms = getPlatformsFromPath(platformsPath);
console.log(green(`\nBundling runtime platform adapters, including: ${platforms}`)); console.log(green(`\nBundling runtime platform adapters, including: ${platforms}`));
for (const platform of platforms) { for (const platform of platforms) {
const engineEntry = normalizePath(ps.join(engineRoot, `platforms/runtime/platforms/${platform}/engine/index.js`));
// Some platform dirs may be incomplete in a checkout (missing engine files);
// skip them instead of crashing the adapter build.
if (!fs.existsSync(engineEntry)) {
console.log(`skip platform: ${platform} (missing ${engineEntry})`);
continue;
}
console.log(`handle platform: ${green(platform)}`); console.log(`handle platform: ${green(platform)}`);
// bundle engine-adapter.js // bundle engine-adapter.js
const engineEntry = normalizePath(ps.join(engineRoot, `platforms/runtime/platforms/${platform}/engine/index.js`));
const engineOutput = normalizePath(ps.join(engineRoot, `bin/adapter/runtime/${platform}/engine-adapter.js`)); const engineOutput = normalizePath(ps.join(engineRoot, `bin/adapter/runtime/${platform}/engine-adapter.js`));
await bundle(engineEntry, engineOutput, true); await bundle(engineEntry, engineOutput, true);
} }
+10 -5
View File
@@ -60,14 +60,19 @@ endfunction()
function(cc_gen_plugin_cmake_hook) function(cc_gen_plugin_cmake_hook)
set(project_root_dir ${CC_PROJECT_DIR}/../../..)
set(load_plugin_cmake ${CC_PROJECT_DIR}/Pre-AutoLoadPlulgins.cmake) set(load_plugin_cmake ${CC_PROJECT_DIR}/Pre-AutoLoadPlulgins.cmake)
message(STATUS "Try generating ${load_plugin_cmake}") message(STATUS "Try generating ${load_plugin_cmake}")
file(REMOVE ${load_plugin_cmake}) file(REMOVE ${load_plugin_cmake})
list(APPEND CC_PLUGIN_PATH # Scan roots default to the native-build project layout; callers that host
${project_root_dir}/native # the scan elsewhere (e.g. the Simulator, pointed at an arbitrary
${project_root_dir}/extensions # extensions tree) may pre-set CC_PLUGIN_PATH with their own roots.
) if(NOT DEFINED CC_PLUGIN_PATH)
set(project_root_dir ${CC_PROJECT_DIR}/../../..)
list(APPEND CC_PLUGIN_PATH
${project_root_dir}/native
${project_root_dir}/extensions
)
endif()
set(plugin_args_info ${CMAKE_CURRENT_BINARY_DIR}/plugin_dirs.txt) set(plugin_args_info ${CMAKE_CURRENT_BINARY_DIR}/plugin_dirs.txt)
file(WRITE ${plugin_args_info} "# directories for searching native plugins\n") file(WRITE ${plugin_args_info} "# directories for searching native plugins\n")
foreach(dir ${CC_PLUGIN_PATH}) foreach(dir ${CC_PLUGIN_PATH})
+438
View File
@@ -0,0 +1,438 @@
import { UIMesh, UIMeshData } from '../../cocos/2d/components/ui-mesh';
import { UITransform } from '../../cocos/2d';
import { UIOpacity } from '../../cocos/2d/components/ui-opacity';
import { Node } from '../../cocos/scene-graph/node';
import { Scene, director } from '../../exports/base';
import { Batcher2D } from '../../cocos/2d/renderer/batcher-2d';
import { vfmtPosUvColor4B, vfmtPosUvTwoColor4B } from '../../cocos/2d/renderer/vertex-format';
import { Vec3 } from '../../cocos/core/math/vec3';
import { captureErrorIDs } from '../utils/log-capture';
// Mirrors sprite.test.ts: a headless batcher so UIMesh can create its shared
// StaticVBAccessor and allocate chunks from it.
// @ts-expect-error
director.root!._batcher = new Batcher2D(director.root!);
const scene = new Scene('uimesh-test');
director.runSceneImmediate(scene);
const ACCESSOR_VERTEX_COUNT = 32767;
function createUIMesh (parent: Node = scene): { mesh: UIMesh, anyMesh: any, node: Node } {
const node = new Node('mesh');
node.addComponent(UITransform);
parent.addChild(node);
const mesh = node.addComponent(UIMesh);
return { mesh, anyMesh: mesh as any, node };
}
function makeMeshData (vc: number, stride = 24): UIMeshData {
const quadCount = Math.floor(vc / 4);
const ic = quadCount * 6;
const vertexData = new Uint8Array(vc * stride);
const indices = new Uint16Array(ic);
for (let q = 0; q < quadCount; ++q) {
const v = q * 4;
const o = q * 6;
indices[o] = v; indices[o + 1] = v + 1; indices[o + 2] = v + 2;
indices[o + 3] = v + 2; indices[o + 4] = v + 1; indices[o + 5] = v + 3;
}
return {
vertexCount: vc,
vertexStride: stride,
vertexData,
indexCount: ic,
indexData: new Uint8Array(indices.buffer),
segments: [{ indexOffset: 0, indexCount: ic, texture: null, material: null }],
};
}
describe('UIMesh: accessor capacity', () => {
test('30000 vertices render — the 10% reserve is clamped to the accessor cap', () => {
const { mesh, anyMesh } = createUIMesh();
const data = makeMeshData(30000); // fits, but ceil(30000 * 1.1) > 32767
mesh.setMeshData(data);
expect(anyMesh._meshData).toBe(data);
expect(anyMesh._prepareBuffers()).not.toBeNull();
const rd = anyMesh._renderData;
// Actual counts are tracked; the reserve lives in the chunk.
expect(rd.vertexCount).toBe(30000);
expect(rd.indexCount).toBe(data.indexCount);
expect(rd.chunk).toBeTruthy();
expect(rd.chunk.vb.byteLength).toBe(ACCESSOR_VERTEX_COUNT * 24);
});
test('32767 vertices (exact accessor cap) render', () => {
const { mesh, anyMesh } = createUIMesh();
mesh.setMeshData(makeMeshData(32767));
expect(anyMesh._prepareBuffers()).not.toBeNull();
const rd = anyMesh._renderData;
expect(rd.vertexCount).toBe(32767);
expect(rd.chunk.vb.byteLength).toBe(ACCESSOR_VERTEX_COUNT * 24);
});
test('data beyond the accessor cap is rejected with an error', () => {
const { mesh, anyMesh } = createUIMesh();
const watcher = captureErrorIDs();
mesh.setMeshData(makeMeshData(32768));
expect(watcher.captured).toHaveLength(1);
expect(watcher.captured[0]).toEqual([9016, 32768, 49152, 32767, 131068]);
watcher.clear();
expect(anyMesh._meshData).toBeNull(); // rejected frame stores nothing
});
test('growth within the reserve does not reallocate the chunk', () => {
const { mesh, anyMesh } = createUIMesh();
mesh.setMeshData(makeMeshData(100));
expect(anyMesh._prepareBuffers()).not.toBeNull();
const chunk = anyMesh._renderData.chunk;
mesh.setMeshData(makeMeshData(105)); // within the ~10% head room
expect(anyMesh._prepareBuffers()).not.toBeNull();
expect(anyMesh._renderData.chunk).toBe(chunk);
expect(anyMesh._renderData.vertexCount).toBe(105);
});
});
describe('UIMesh: setMeshData boundary validation', () => {
let mesh: UIMesh;
let anyMesh: any;
let watcher: ReturnType<typeof captureErrorIDs>;
beforeEach(() => {
({ mesh, anyMesh } = createUIMesh());
watcher = captureErrorIDs();
});
// The watcher must be empty by test end (log-capture afterEach enforces it):
// every test asserts its single errorID call and clears it. Entries are the
// raw errorID arguments — [id, ...params]; the texts live in DebugInfos.json.
afterEach(() => {
watcher.clear();
});
test('rejects unsupported vertex stride', () => {
mesh.setMeshData(makeMeshData(8, 32));
expect(watcher.captured).toHaveLength(1);
expect(watcher.captured[0]).toEqual([9010, 32, 24, 28]);
expect(anyMesh._meshData).toBeNull();
});
test('rejects vertexData shorter than vertexCount * stride', () => {
const data = makeMeshData(8);
data.vertexData = data.vertexData.slice(0, data.vertexData.byteLength - 1);
mesh.setMeshData(data);
expect(watcher.captured).toHaveLength(1);
expect(watcher.captured[0]).toEqual([9012, 191, 8, 24]);
expect(anyMesh._meshData).toBeNull();
});
test('rejects indexData shorter than indexCount * 2', () => {
const data = makeMeshData(8);
data.indexData = data.indexData.slice(0, data.indexData.byteLength - 2);
mesh.setMeshData(data);
expect(watcher.captured).toHaveLength(1);
expect(watcher.captured[0]).toEqual([9013, 22, 0, 12, 24]);
expect(anyMesh._meshData).toBeNull();
});
test('rejects indices out of vertex range', () => {
const data = makeMeshData(8);
const indices = new Uint16Array(data.indexData.buffer, data.indexData.byteOffset, data.indexCount);
indices[0] = data.vertexCount; // one past the last vertex
mesh.setMeshData(data);
expect(watcher.captured).toHaveLength(1);
expect(watcher.captured[0]).toEqual([9014, 0, 8, 8]);
expect(anyMesh._meshData).toBeNull();
});
test('rejects segment ranges beyond indexCount', () => {
const data = makeMeshData(8);
data.segments = [{ indexOffset: 0, indexCount: data.indexCount + 1, texture: null, material: null }];
mesh.setMeshData(data);
expect(watcher.captured).toHaveLength(1);
expect(watcher.captured[0]).toEqual([9015, 0, 0, 13, 12]);
expect(anyMesh._meshData).toBeNull();
});
test('a rejected frame keeps the last accepted mesh', () => {
const good = makeMeshData(8);
mesh.setMeshData(good);
mesh.setMeshData(makeMeshData(32768)); // over cap, rejected
expect(watcher.captured).toHaveLength(1);
expect(watcher.captured[0]).toEqual([9016, 32768, 49152, 32767, 131068]);
expect(anyMesh._meshData).toBe(good);
});
});
describe('UIMesh: accessor lifetime follows the batcher', () => {
test('a rebuilt root/batcher never reuses a destroyed accessor (single- and two-color)', () => {
const UIMESH_KEY = Number.parseInt('UIMESH', 36);
const UIMESH_TINT_KEY = Number.parseInt('UIMESHTINT', 36);
// First root: a UIMesh creates its accessors and registers them with
// the current batcher.
const first = createUIMesh();
first.mesh.setMeshData(makeMeshData(8));
expect(first.anyMesh._prepareBuffers()).not.toBeNull();
const oldAccessor = first.anyMesh._renderData.accessor;
const oldMap: Map<number, any> = (director.root!.batcher2D as any)._bufferAccessors;
expect(oldMap.get(UIMESH_KEY)).toBe(oldAccessor); // registered with its batcher
// Root.destroy(): the batcher destroys every accessor it owns, is
// dropped, and a rebuilt root creates a fresh batcher with an empty map
// — all within the same JS context.
const root: any = director.root!;
const oldBatcher: Batcher2D = root.batcher2D;
oldBatcher.destroy();
expect(oldMap.size).toBe(0); // accessors released with the batcher
expect((oldAccessor as any)._buffers.length).toBe(0); // buffers gone
root._batcher = new Batcher2D(root);
// UIMesh components under the new root must resolve fresh accessors
// from the new batcher. A batcher-keyed cache that forgot to invalidate
// would hand back the destroyed accessor and skip registration,
// breaking upload/reset.
const second = createUIMesh();
second.mesh.setMeshData(makeMeshData(8));
expect(second.anyMesh._prepareBuffers()).not.toBeNull();
const newAccessor = second.anyMesh._renderData.accessor;
expect(newAccessor).not.toBe(oldAccessor);
expect((newAccessor as any)._buffers.length).toBeGreaterThan(0);
const newMap: Map<number, any> = (director.root!.batcher2D as any)._bufferAccessors;
expect(newMap.get(UIMESH_KEY)).toBe(newAccessor); // registered with the new batcher
// Two-color branch: same guarantee for the tint accessor.
const tinted = createUIMesh();
tinted.mesh.setMeshData(makeMeshData(8, 28));
expect(tinted.anyMesh._prepareBuffers()).not.toBeNull();
const newTintAccessor = tinted.anyMesh._renderData.accessor;
expect(newTintAccessor).not.toBe(oldAccessor);
expect(newMap.get(UIMESH_TINT_KEY)).toBe(newTintAccessor);
// The accessors hold copies of the vertex formats: destroying them with
// the old batcher must not empty the shared module-level constants.
expect(vfmtPosUvColor4B).toHaveLength(3);
expect(vfmtPosUvTwoColor4B).toHaveLength(4);
});
});
// A drawable segment: a texture is what makes _prepareNativeDrawInfos create a
// draw info (segments without texture are skipped). Only getGFXTexture /
// getGFXSampler are called headless.
const fakeTexture = (): any => ({ getGFXTexture: () => ({}), getGFXSampler: () => ({}) });
function makeDrawnData (vc: number): UIMeshData {
const data = makeMeshData(vc);
data.segments = [{ indexOffset: 0, indexCount: data.indexCount, texture: fakeTexture(), material: {} as any }];
return data;
}
describe('UIMesh: per-frame index submission (native cross-frame)', () => {
// The native batcher resets every mesh buffer's index tail after upload
// (indexOffset = 0, synchronized through shared memory) while only dirty
// renderers re-prepare. jest runs with JSB = false, so these tests drive
// the JSB pump's two submit paths directly: appendIndexBuffer (static
// frame) and _prepareNativeDrawInfos (dirty frame) -- each runs exactly
// once per frame. The helper below performs the post-upload reset.
const nextFrame = (buf: any): void => {
buf.indexOffset = 0; // the post-upload index-tail reset
};
test('a paused mesh keeps drawing its own triangles while a sibling updates', () => {
const a = createUIMesh();
const b = createUIMesh();
a.mesh.setMeshData(makeDrawnData(4)); // ic = 6
b.mesh.setMeshData(makeDrawnData(4));
// Frame 1: both dirty -> both run the native draw-info refresh.
a.anyMesh._prepareNativeDrawInfos();
b.anyMesh._prepareNativeDrawInfos();
const buf = a.anyMesh._renderData.getMeshBuffer();
expect(b.anyMesh._renderData.getMeshBuffer()).toBe(buf); // one shared buffer
const offsetA = a.anyMesh._renderData.chunk.vertexOffset;
const offsetB = b.anyMesh._renderData.chunk.vertexOffset;
expect(offsetB).toBeGreaterThan(offsetA);
const quadOf = (o: number): Uint16Array => new Uint16Array([o, o + 1, o + 2, o + 2, o + 1, o + 3]);
const startA = a.anyMesh._drawInfoList[0]._indexOffset;
const startB = b.anyMesh._drawInfoList[0]._indexOffset;
expect(startB - startA).toBe(6); // B appended right after A
expect(buf.iData.slice(startA, startA + 6)).toEqual(quadOf(offsetA));
expect(buf.iData.slice(startB, startB + 6)).toEqual(quadOf(offsetB));
// Frame 2: A paused (no setMeshData), B advancing.
nextFrame(buf);
b.mesh.setMeshData(makeDrawnData(4)); // B's producer, update phase
a.anyMesh.appendIndexBuffer(); // A's pump: static, index-only resubmit
b.anyMesh._prepareNativeDrawInfos(); // B's pump: dirty, full refresh
// A's cached draw info still points at a range holding A's OWN indices.
// Without the per-frame resubmit, B would append at the reset offset 0
// and A (start 0, never refreshed) would draw B's vertices.
expect(a.anyMesh._drawInfoList[0]._indexOffset).toBe(0);
expect(b.anyMesh._drawInfoList[0]._indexOffset).toBe(6);
expect(buf.iData.slice(0, 6)).toEqual(quadOf(offsetA));
expect(buf.iData.slice(6, 12)).toEqual(quadOf(offsetB));
expect(buf.indexOffset).toBe(12); // one append per mesh — the pump is the single driver
});
test('each frame appends once; re-feeding the same object resubmits', () => {
const { mesh, anyMesh } = createUIMesh();
const data = makeMeshData(4);
mesh.setMeshData(data);
expect(anyMesh._prepareBuffers()).not.toBeNull(); // establishes the chunk
const buf = anyMesh._renderData.getMeshBuffer();
const offset = anyMesh._renderData.chunk.vertexOffset;
const quadOf = (o: number): Uint16Array => new Uint16Array([o, o + 1, o + 2, o + 2, o + 1, o + 3]);
nextFrame(buf);
anyMesh.appendIndexBuffer(); // the pump's static-frame path
expect(buf.indexOffset).toBe(6);
expect(buf.iData.slice(0, 6)).toEqual(quadOf(offset));
nextFrame(buf);
mesh.setMeshData(data); // SAME object, mutated in place by the producer
anyMesh.appendIndexBuffer();
expect(buf.indexOffset).toBe(6); // setMeshData latched a refresh; fresh append at the reset tail
expect(buf.iData.slice(0, 6)).toEqual(quadOf(offset));
});
});
describe('UIMesh: batched bake applies the full world matrix', () => {
const writePositions = (data: UIMeshData, locals: Vec3[]): void => {
const floats = new Float32Array(data.vertexData.buffer, data.vertexData.byteOffset, data.vertexData.byteLength >> 2);
locals.forEach((v, i) => {
floats[i * 6] = v.x; floats[i * 6 + 1] = v.y; floats[i * 6 + 2] = v.z;
});
};
const chunkPosition = (anyMesh: any, i: number): Vec3 => {
const vb = anyMesh._renderData.chunk.vb; // stride 24 = 6 floats
return new Vec3(vb[i * 6], vb[i * 6 + 1], vb[i * 6 + 2]);
};
test('a parent Z translation reaches the batched vertices: local (1,2,3) + z+10 -> (1,2,13)', () => {
const parent = new Node('parent');
parent.addComponent(UITransform);
scene.addChild(parent);
parent.setPosition(0, 0, 10);
const { mesh, anyMesh } = createUIMesh(parent); // node itself stays identity
const data = makeMeshData(4);
writePositions(data, [new Vec3(1, 2, 3), new Vec3(-1, 2, 3), new Vec3(1, -2, -3), new Vec3(-1, -2, -3)]);
anyMesh._enableBatch = true; // direct: the public setter also recompiles materials
mesh.setMeshData(data);
expect(anyMesh._prepareBuffers()).not.toBeNull();
// The old 2D-only bake kept z at 3; the GPU path (pos = cc_matWorld * pos)
// produces 13, and so must the baked chunk.
const got = chunkPosition(anyMesh, 0);
expect(got.x).toBeCloseTo(1, 6);
expect(got.y).toBeCloseTo(2, 6);
expect(got.z).toBeCloseTo(13, 6);
});
test('batched chunk equals the full world matrix applied to the unbatched chunk (toggle consistency)', () => {
const parent = new Node('parent');
parent.addComponent(UITransform);
scene.addChild(parent);
parent.setPosition(1, 2, 10);
parent.setRotationFromEuler(30, 0, 0); // X-axis rotation
const { mesh, anyMesh, node } = createUIMesh(parent);
node.setPosition(0.5, -0.25, 2);
node.setRotationFromEuler(0, 45, 0); // Y-axis rotation
const locals = [new Vec3(1, 2, 3), new Vec3(-4, 5, -6), new Vec3(7, -8, 9), new Vec3(-10, -11, -12)];
const data = makeMeshData(4);
writePositions(data, locals);
// Unbatched: the chunk stays node-local (the GPU applies cc_matWorld).
anyMesh._enableBatch = false;
mesh.setMeshData(data);
expect(anyMesh._prepareBuffers()).not.toBeNull();
const localChunk = [0, 1, 2, 3].map((i) => chunkPosition(anyMesh, i));
// Batched: the chunk holds the world matrix baked on the CPU. What the
// GPU would compute for the unbatched data and what the batched data
// carries must agree component by component, z and X/Y rotation included.
anyMesh._enableBatch = true;
expect(anyMesh._prepareBuffers()).not.toBeNull();
const wm = node.worldMatrix;
for (let i = 0; i < 4; i++) {
const expected = new Vec3();
Vec3.transformMat4(expected, localChunk[i], wm);
const got = chunkPosition(anyMesh, i);
expect(got.x).toBeCloseTo(expected.x, 5);
expect(got.y).toBeCloseTo(expected.y, 5);
expect(got.z).toBeCloseTo(expected.z, 5);
}
// The JSB staleness poll must track the full matrix the bake consumes:
// a paused mesh that moves in Z or rotates in X/Y still has to re-bake.
// The capture after a batched prepare is exactly what _onBeforeDraw
// compares against on the next frame.
expect(Math.abs(wm.m02)).toBeGreaterThan(0.5); // the rotations are live
expect(anyMesh._pollWorldMatrix.strictEquals(wm)).toBe(true);
});
});
describe('UIMesh: cascaded opacity includes ancestor renderer color.a', () => {
const makeParentWithRenderer = (alpha: number): { parent: Node, parentMesh: any } => {
const parent = new Node('parent');
parent.addComponent(UITransform);
scene.addChild(parent);
const parentMesh = parent.addComponent(UIMesh) as any;
parentMesh._color.a = alpha; // direct write: the setter drags color-update machinery in
return { parent, parentMesh };
};
test('a parent renderer at color.a 128 fades the child to ~0.502', () => {
const { parent } = makeParentWithRenderer(128);
const { anyMesh } = createUIMesh(parent);
// Own alpha 255 x parent level (UIOpacity 1 x renderer 128/255). The old
// computation stopped at localOpacity and returned 1 here.
expect(anyMesh._computeCascadedOpacity()).toBeCloseTo(128 / 255, 6);
});
test('UIOpacity localOpacity and renderer alpha accumulate at every ancestor level', () => {
const grand = new Node('grand');
grand.addComponent(UITransform);
scene.addChild(grand);
grand.addComponent(UIOpacity).opacity = 204; // localOpacity 0.8
const parent = new Node('parent');
parent.addComponent(UITransform);
grand.addChild(parent);
const parentMesh = parent.addComponent(UIMesh) as any;
parentMesh._color.a = 128;
parent.addComponent(UIOpacity).opacity = 128; // localOpacity 128/255
const { anyMesh } = createUIMesh(parent);
expect(anyMesh._computeCascadedOpacity()).toBeCloseTo((204 / 255) * (128 / 255) * (128 / 255), 6);
});
test('a paused mesh picks up ancestor color.a changes (the JSB poll input)', () => {
const { parent, parentMesh } = makeParentWithRenderer(128);
const { mesh, anyMesh } = createUIMesh(parent);
const data = makeMeshData(4);
// vfmtPosUvColor4B: pos 12B + uv 8B puts the color attribute at bytes
// 20..23 of the 24-byte vertex — alpha lives at 23.
for (let i = 0; i < 4; i++) data.vertexData[i * 24 + 23] = 255; // opaque alpha bytes
mesh.setMeshData(data);
expect(anyMesh._prepareBuffers()).not.toBeNull();
expect(anyMesh._pollOpacity).toBeCloseTo(128 / 255, 6); // captured by the last active frame
// The ancestor fades while this mesh is paused: no engine event marks a
// middleware renderer dirty -- the update() poll compares exactly this
// value and re-marks on drift.
parentMesh._color.a = 64;
expect(anyMesh._computeCascadedOpacity()).not.toBe(anyMesh._pollOpacity);
// The refresh the poll triggers re-folds the new opacity into the
// copied vertices' alpha bytes.
expect(anyMesh._prepareBuffers()).not.toBeNull();
expect(anyMesh._pollOpacity).toBeCloseTo(64 / 255, 6);
const vb = anyMesh._renderData.chunk.vb;
const bytes = new Uint8Array(vb.buffer, vb.byteOffset, 4 * 24);
for (let i = 0; i < 4; i++) {
expect(bytes[i * 24 + 23]).toBe(64); // 255 * (64 / 255)
}
});
});