Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

fix(cocos): a renderer is put in the layer of its Cocos node, so a UI camera that culls by layer draws it

yhhafebc9cec275
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 23b28b32d..3a0f51837 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -20,6 +20,7 @@ published separately; it ships inside the editor.
- **Scroll areas can be pulled past an end and spring back.** A scroll area whose movement is Elastic now does what the setting always said: a drag past an end is stiffer the further out it goes, letting go returns the content, and a flick that reaches an end bounces off it. It is opt-in per area (`ScrollMovement.Elastic`; Clamped, the default, behaves as before), and the gesture model (`ScrollMotion`, with `ScrollContainer.dragTo` and `getOverscroll`) is exported for scrolling anything else the same way.
- **More easing curves.** Sine, quart, quint, expo and circ (each in, out and in-out), bounce in and in-out, and smoothstep and smootherstep join the quad, cubic, back, elastic and out-bounce curves. They are new `EasingType` members after the existing ones, so a saved tween keeps its curve, and they ease the same in a C++ tween and a script value tween.
- **World content has a rectangle: `ContentRect`.** A size and the pivot the entity's transform sits on, which the `Sprite` and `Text` on the entity follow and which a `UIMask` on it clips to — no `UINode` needed, so a clipping region or a scroll viewport can stand in the world. `contentRectContains` tests a world point against it.
+- **A Cocos node layer is its renderers layer.** The sprites, texts, shapes, spine, particles and meshes of a converted node are put in the layer the node had in Cocos (its bit index), which is what a camera culling mask selects among. A UI camera that draws only layer 25 used to draw none of the sprites left in layer 0, so the converted game launch scene was black.
- **A converted Cocos project starts as the game does.** The project opens at the Cocos launch scene (not the starter empty scene) and its design size, scripts that only define globals (the game configuration) run before the ones scenes name, and the editor built-in assets a scene names by uuid (the default progress bar images) are read from the Creator install, which took the missing sprite frames of the client from 385 to 15.
- **Cocos layer components survive a replay.** The components the layer declares (Widget, Button, ProgressBar, ScrollView and the rest) are counted among the engine own, so clearing the registry for a replay no longer drops them, and the host walks its script query before running scripts, so a script that switches nodes on in `start` does not meet a walked query.
- **A material colour is the renderer tint.** The engine keeps a mesh colour on the renderer, not in a shader parameter, so `mainColor`, `albedo`, `baseColor` and `color` set on a renderer own material instance write its tint and read back from it.
diff --git a/pipeline/src/import/cocos/components.ts b/pipeline/src/import/cocos/components.ts
index 65c80e3d4..fe051489a 100644
--- a/pipeline/src/import/cocos/components.ts
+++ b/pipeline/src/import/cocos/components.ts
@@ -813,6 +813,9 @@ function script(c: CocosComponent, ctx: ComponentContext): ComponentData | null
return { type: `${LAYER}${cls.name}`, data };
}
+/** The engine components that draw, and carry the layer a camera's culling mask selects. */
+const LAYERED = new Set(['Sprite', 'Text', 'ShapeRenderer', 'SpineAnimation', 'ParticleEmitter', 'MeshRenderer']);
+
/** Components that are folded into another, or carry nothing of their own. */
const FOLDED = new Set(['cc.UITransform', 'cc.LabelOutline', 'cc.LabelShadow', 'cc.Canvas', 'cc.UIMeshRenderer', 'cc.RenderRoot2D']);
@@ -985,6 +988,12 @@ export function convertNode(node: CocosNode, ctx: ComponentContext, where: strin
unmapped.push({ type: c.type, enabled: c.enabled, data: c.data });
}
+ // A node's Cocos layer is the layer its renderers draw in: a camera's culling mask picks among those, and a renderer left in layer 0 is
+ // outside the mask of a UI camera (layer 25) and never drawn by it.
+ const layerBit = node.layer > 0 && (node.layer & (node.layer - 1)) === 0 ? Math.log2(node.layer) : -1;
+ if (layerBit >= 0 && layerBit < 32) {
+ for (const c of [...components, ...extra]) if (LAYERED.has(c.type) && !(c.data.layer)) c.data.layer = layerBit;
+ }
components.push(...extra);
if (unitScale !== 1) {
const scale = components[0]!.data.scale as { x: number; y: number; z: number };
diff --git a/pipeline/tests/cocos-import-layer.test.ts b/pipeline/tests/cocos-import-layer.test.ts
index 8b2010e78..024004c4d 100644
--- a/pipeline/tests/cocos-import-layer.test.ts
+++ b/pipeline/tests/cocos-import-layer.test.ts
@@ -212,6 +212,12 @@ describe('importing for the compatibility layer', () => {
expect(at("scripts/Globals'")).toBeLessThan(at("scripts/Hud'"));
});
+ it('puts a renderer in the layer of its node, which is what a UI camera culls by', () => {
+ const sprites = scenes.entities.flatMap((e) => e.components.filter((c) => c.type === 'Sprite'));
+ expect(sprites.length).toBeGreaterThan(0);
+ for (const sprite of sprites) expect(sprite.data.layer).toBe(25);
+ });
+
it('counts the components it maps', () => {
for (const type of ['cc.Widget', 'cc.Layout', 'cc.Button', 'cc.UITransform']) expect(report.components[type]!.unmapped).toBe(0);
});
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 9e946494c..262f55dfc 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -28,6 +28,8 @@ export const NOTES_FLOOR = 'v0.65.0';
* the reader recognises anyway.
*/
export const NOTED = {
+ 'fix(cocos): a renderer is put in the layer of its Cocos node, so a UI camera that culls by layer draws it':
+ {"note":"A Cocos node layer is its renderers layer."},
'feat(cocos): a converted project starts at the game launch scene and runs its global-defining scripts first, reads the editor built-in assets, and the layer components survive a replay':
{"note":"A converted Cocos project starts as the game does."},
'feat(cocos): the colour a script sets on a material instance is the renderer tint':