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.

feat(cocos): a converted project keeps the Cocos fit width of its design, and cc.profiler exists in the compatibility layer

yhh6a87ed188240
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3a0f51837..f2a912924 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 converted Cocos project fits the screen as the game does.** The Cocos design fit (fit width, fit height) becomes the project camera scale mode (fixed width, fixed height), so a UI laid out in design units comes out the same size on every screen instead of being drawn at the window pixel size. `cc.profiler` (`showStats`, `hideStats`) is accepted by the compatibility layer.
- **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.
diff --git a/pipeline/src/import/cocos/importProject.ts b/pipeline/src/import/cocos/importProject.ts
index 6574897bc..e89a08a50 100644
--- a/pipeline/src/import/cocos/importProject.ts
+++ b/pipeline/src/import/cocos/importProject.ts
@@ -158,7 +158,7 @@ function startSceneOf(scenes: readonly string[]): string | undefined {
*/
function wireManifest(out: string, source: string, into: string, scenes: readonly string[]): void {
const file = path.join(out, 'project.esproject');
- let manifest: { defaultScene?: string; designResolution?: { width?: number; height?: number } };
+ let manifest: { defaultScene?: string; designResolution?: { width?: number; height?: number }; features?: { rendering?: { cameraScaleMode?: string } } };
try {
manifest = JSON.parse(readFileSync(file, 'utf8'));
} catch {
@@ -171,8 +171,15 @@ function wireManifest(out: string, source: string, into: string, scenes: readonl
changed = true;
}
try {
- const settings = JSON.parse(readFileSync(path.join(source, 'settings', 'v2', 'packages', 'project.json'), 'utf8')) as { general?: { designResolution?: { width?: number; height?: number } } };
+ const settings = JSON.parse(readFileSync(path.join(source, 'settings', 'v2', 'packages', 'project.json'), 'utf8')) as { general?: { designResolution?: { width?: number; height?: number; fitWidth?: boolean; fitHeight?: boolean } } };
const size = settings.general?.designResolution;
+ // Fit width (and not height) keeps the design width across the screen and lets the height follow the window: Cocos's FIXED_WIDTH, which is what
+ // a UI laid out in design units needs to come out the same size on every screen.
+ const fit = size?.fitWidth && !size.fitHeight ? 'fixed-width' : size?.fitHeight && !size.fitWidth ? 'fixed-height' : undefined;
+ if (fit && !manifest.features?.rendering?.cameraScaleMode) {
+ manifest.features = { ...manifest.features, rendering: { ...manifest.features?.rendering, cameraScaleMode: fit } };
+ changed = true;
+ }
const dr = manifest.designResolution;
if (size?.width && size.height && (!dr || (dr.width === 800 && dr.height === 600))) {
manifest.designResolution = { width: size.width, height: size.height };
diff --git a/pipeline/tests/cocos-import-layer.test.ts b/pipeline/tests/cocos-import-layer.test.ts
index 024004c4d..25b1998c2 100644
--- a/pipeline/tests/cocos-import-layer.test.ts
+++ b/pipeline/tests/cocos-import-layer.test.ts
@@ -93,7 +93,7 @@ describe('importing for the compatibility layer', () => {
mkdirSync(path.join(root, 'out', 'src'), { recursive: true });
writeFileSync(path.join(root, 'out', 'project.esproject'), JSON.stringify({ formatVersion: '1', name: 'x', defaultScene: 'assets/scenes/main.esscene', designResolution: { width: 800, height: 600 } }));
mkdirSync(path.join(root, 'creator', 'settings', 'v2', 'packages'), { recursive: true });
- writeFileSync(path.join(root, 'creator', 'settings', 'v2', 'packages', 'project.json'), JSON.stringify({ general: { designResolution: { width: 1080, height: 1920 } } }));
+ writeFileSync(path.join(root, 'creator', 'settings', 'v2', 'packages', 'project.json'), JSON.stringify({ general: { designResolution: { width: 1080, height: 1920, fitWidth: true, fitHeight: false } } }));
writeFileSync(path.join(root, 'out', 'src', 'main.ts'), "// Game entry.\nimport './components';\n");
report = await importCocosProject({ source: path.join(root, 'creator'), out: path.join(root, 'out') });
scenes = JSON.parse(readFileSync(path.join(root, 'out', 'assets', 'cocos', 'main.esscene'), 'utf8'));
@@ -203,6 +203,7 @@ describe('importing for the compatibility layer', () => {
const manifest = JSON.parse(readFileSync(path.join(root, 'out', 'project.esproject'), 'utf8')) as { defaultScene: string; designResolution: { width: number; height: number } };
expect(manifest.defaultScene).toBe('assets/cocos/main.esscene');
expect(manifest.designResolution).toEqual({ width: 1080, height: 1920 });
+ expect((manifest as { features?: { rendering?: { cameraScaleMode?: string } } }).features?.rendering?.cameraScaleMode).toBe('fixed-width');
});
it('runs a script that only defines globals before the scripts scenes name', () => {
diff --git a/sdk/src/cocos/index.ts b/sdk/src/cocos/index.ts
index 6ea35f459..24a8657ab 100644
--- a/sdk/src/cocos/index.ts
+++ b/sdk/src/cocos/index.ts
@@ -27,7 +27,7 @@ export {
} from './assets';
export { registerBuiltinComponent, type BuiltinAdapter } from './builtins';
export { unsupported } from './unsupported';
-export { ccenum, js, NodePool } from './misc';
+export { ccenum, js, NodePool, profiler } from './misc';
export { MeshRenderer, ModelRenderer, UIMeshRenderer } from './meshRenderer';
export { geometry } from './geometry';
export { UITransform, Label, LabelOutline, LabelShadow, Sprite, UIOpacity, Button, EventHandler, Widget, Layout, Camera, RichText, Mask, Toggle, ToggleContainer, ProgressBar, Slider, BlockInputEvents, ScrollView, Graphics, Line, EditBox, PageView, PageViewIndicator, ScrollBar, SafeArea, WebView, getVisibleSize, setVisibleSize } from './ui';
diff --git a/sdk/src/cocos/misc.ts b/sdk/src/cocos/misc.ts
index ec51f7e41..d6ed67442 100644
--- a/sdk/src/cocos/misc.ts
+++ b/sdk/src/cocos/misc.ts
@@ -99,3 +99,15 @@ export class NodePool {
return node.getComponent(this.handler_ as never) as unknown as { unuse?(): void; reuse?(args: unknown[]): void } | null;
}
}
+
+/**
+ * `profiler`: the engine's on-screen statistics panel. Showing it is the editor's profiler and the host's overlay here, not a node a script
+ * owns, so the calls are accepted and the state is only remembered for `isShowingStats`.
+ */
+let showingStats = false;
+export const profiler = {
+ showStats(): void { showingStats = true; },
+ hideStats(): void { showingStats = false; },
+ isShowingStats(): boolean { return showingStats; },
+ generateNode(): void { /* the panel is not a node here */ },
+};
diff --git a/sdk/tests/cocos/misc.test.ts b/sdk/tests/cocos/misc.test.ts
index ae665821c..b9b0c2e52 100644
--- a/sdk/tests/cocos/misc.test.ts
+++ b/sdk/tests/cocos/misc.test.ts
@@ -1,7 +1,7 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import { describe, expect, it } from 'vitest';
-import { NodePool, ccenum, js } from '../../src/cocos/misc';
+import { NodePool, ccenum, js, profiler } from '../../src/cocos/misc';
import type { Node } from '../../src/cocos/node';
/** The parts of a node a pool touches. */
@@ -70,3 +70,13 @@ describe('js and ccenum', () => {
expect(ccenum(Mode)).toBe(Mode);
});
});
+
+describe('profiler', () => {
+ it('takes show and hide, and remembers which', () => {
+ expect(profiler.isShowingStats()).toBe(false);
+ profiler.showStats();
+ expect(profiler.isShowingStats()).toBe(true);
+ profiler.hideStats();
+ expect(profiler.isShowingStats()).toBe(false);
+ });
+});
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 262f55dfc..7d391d07a 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 = {
+ 'feat(cocos): a converted project keeps the Cocos fit width of its design, and cc.profiler exists in the compatibility layer':
+ {"note":"A converted Cocos project fits the screen as the game does."},
'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':