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(assets): the plane of Cocos imports as builtin:cocos-plane, 10 across like the one effects were written against, so what an effect reads of its position in the mesh's own space has the scale it expects

yhh89e3bde058fd
diff --git a/docs/astro/src/content/docs/assets/models.mdx b/docs/astro/src/content/docs/assets/models.mdx
index b71dc1742..65d3ef12c 100644
--- a/docs/astro/src/content/docs/assets/models.mdx
+++ b/docs/astro/src/content/docs/assets/models.mdx
@@ -19,7 +19,7 @@ That import is the subject of this page. For the component that draws the result
## Built-in primitives
Seven shapes need no import and no file. **+ Add → Create entity… → Cube** (or Sphere, Capsule, Cylinder,
-Cone, Plane, Map Plane, Quad) makes an entity whose `MeshRenderer.mesh` holds a `builtin:` ref, and the
+Cone, Plane, Cocos Plane, Quad) makes an entity whose `MeshRenderer.mesh` holds a `builtin:` ref, and the
same eight appear at the top of the picker on any `MeshRenderer.mesh` field.
| Ref | Shape |
@@ -30,7 +30,7 @@ same eight appear at the top of the picker on any `MeshRenderer.mesh` field.
| `builtin:cylinder` | 100-unit upright cylinder, flat caps |
| `builtin:cone` | 100-unit cone standing on its base |
| `builtin:plane` | 100-unit square in XZ, facing up — a ground |
-| `builtin:map-plane` | the same square with the v of its texture running along +z, as a map seen from above has it (the plane of Cocos Creator) |
+| `builtin:cocos-plane` | the ground square of Cocos Creator: 10 units across, the v of its texture running along +z as a map's does — what an effect written against Cocos's plane reads |
| `builtin:quad` | 100-unit square in XY, facing the camera — a backdrop |
They are built in code at load time, so they cost no bytes in a package and a scene that
diff --git a/docs/astro/src/content/docs/zh-cn/assets/models.mdx b/docs/astro/src/content/docs/zh-cn/assets/models.mdx
index 0feeb991f..f075cafb0 100644
--- a/docs/astro/src/content/docs/zh-cn/assets/models.mdx
+++ b/docs/astro/src/content/docs/zh-cn/assets/models.mdx
@@ -16,7 +16,7 @@ import { Aside } from '@astrojs/starlight/components';
## 内置图元
有八个形状不需要导入、也不需要文件。**+ 添加 → 创建实体… → Cube**(以及 Sphere、Capsule、Cylinder、
-Cone、Plane、Map Plane、Quad)建出的实体,其 `MeshRenderer.mesh` 里放的是一个 `builtin:` 引用;同样这八个
+Cone、Plane、Cocos Plane、Quad)建出的实体,其 `MeshRenderer.mesh` 里放的是一个 `builtin:` 引用;同样这八个
也排在任何 `MeshRenderer.mesh` 字段选择器的最前面。
| 引用 | 形状 |
@@ -27,7 +27,7 @@ Cone、Plane、Map Plane、Quad)建出的实体,其 `MeshRenderer.mesh` 里
| `builtin:cylinder` | 100 单位的竖直圆柱,平顶平底 |
| `builtin:cone` | 100 单位的圆锥,立在底面上 |
| `builtin:plane` | XZ 平面上 100 单位的方块,朝上 —— 一块地面 |
-| `builtin:map-plane` | 同样的方块,贴图的 v 沿 +z 方向,和从上往下看的地图一样(Cocos Creator 的平面) |
+| `builtin:cocos-plane` | Cocos Creator 的地面方块:宽 10 单位,贴图的 v 沿 +z 方向,和地图一样 —— 按 Cocos 的平面写的效果读的就是它 |
| `builtin:quad` | XY 平面上 100 单位的方块,正对相机 —— 一块背板 |
它们在加载时由代码生成,所以在包里不占任何字节,引用了它的场景也不因此多出依赖。八个都
diff --git a/pipeline/src/import/cocos/components.ts b/pipeline/src/import/cocos/components.ts
index 6facf610d..f0c629282 100644
--- a/pipeline/src/import/cocos/components.ts
+++ b/pipeline/src/import/cocos/components.ts
@@ -611,11 +611,11 @@ function skeletalAnimation(c: CocosComponent, node: CocosNode, ctx: ComponentCon
* so the node's scale carries the difference and the shape stays the size the scene meant.
*/
const COCOS_PRIMITIVES = '1263d74c-8167-4928-91a6-4e2672411f47';
-const PRIMITIVE_MESHES: Record<string, { ref: string; size: number }> = {
+const PRIMITIVE_MESHES: Record<string, { ref: string; size: number; engineSize?: number }> = {
a804a: { ref: 'builtin:cube', size: 1 },
'17020': { ref: 'builtin:sphere', size: 1 },
'38fd2': { ref: 'builtin:cylinder', size: 1 },
- '2e76e': { ref: 'builtin:map-plane', size: 10 },
+ '2e76e': { ref: 'builtin:cocos-plane', size: 10, engineSize: 10 },
fc873: { ref: 'builtin:quad', size: 1 },
};
const ENGINE_PRIMITIVE_SIZE = 100;
@@ -663,7 +663,7 @@ function meshRenderer(c: CocosComponent, ctx: ComponentContext, where: string):
}
const data: Raw = { mesh: primitive.ref, enabled: c.enabled };
const applied = applyMaterial(data, c, ctx, where);
- return { component: { type: 'MeshRenderer', data }, scale: primitive.size / ENGINE_PRIMITIVE_SIZE, partial: hasMaterial && !applied.exact };
+ return { component: { type: 'MeshRenderer', data }, scale: primitive.size / (primitive.engineSize ?? ENGINE_PRIMITIVE_SIZE), partial: hasMaterial && !applied.exact };
}
const found = meshUuid ? ctx.modelMesh?.(meshUuid) : null;
if (!found) {
diff --git a/pipeline/src/import/cocos/importProject.ts b/pipeline/src/import/cocos/importProject.ts
index 7166d5cc8..e240378db 100644
--- a/pipeline/src/import/cocos/importProject.ts
+++ b/pipeline/src/import/cocos/importProject.ts
@@ -31,7 +31,7 @@ import { convertPass, isOutlinePass, type PassConversion } from './effectConvert
* importer that made less (or differently), and is brought up to date when it is opened. Raise it when the converted output changes in a
* way an existing project needs to pick up: a new generated file, a field a document or a manifest now carries.
*/
-export const COCOS_IMPORT_REVISION = 16;
+export const COCOS_IMPORT_REVISION = 17;
/** Whether the project at @p projectRoot was written by an importer of this revision. A project that was not converted has nothing to bring up. */
export function cocosImportIsCurrent(projectRoot: string): boolean {
diff --git a/sdk/src/asset/builtinMeshes.ts b/sdk/src/asset/builtinMeshes.ts
index 3a41ba380..3508d2404 100644
--- a/sdk/src/asset/builtinMeshes.ts
+++ b/sdk/src/asset/builtinMeshes.ts
@@ -201,8 +201,8 @@ function plane(size: number): Builder {
return b;
}
-/** The plane with v running along +z, so a picture laid over it reads as a map seen from above with +z towards the viewer: the plane of Cocos. */
-function mapPlane(size: number): Builder {
+/** The plane of Cocos Creator: v runs along +z, so a picture laid over it reads as a map seen from above with +z towards the viewer. */
+function cocosPlane(size: number): Builder {
const b = newBuilder();
const h = size / 2;
quadFace(b, [[-h, 0, h], [h, 0, h], [h, 0, -h], [-h, 0, -h]], [0, 1, 0], true);
@@ -276,8 +276,9 @@ export const BUILTIN_MESH_TEMPLATES: readonly BuiltinMeshTemplate[] = [
() => cone(UNIT / 2, UNIT)),
template('plane', 'Plane', `A ${UNIT}-unit ground square in XZ, facing up.`, false,
() => plane(UNIT)),
- template('map-plane', 'Map Plane', `A ${UNIT}-unit ground square in XZ, facing up, whose texture's v runs along +z as a map's does.`, false,
- () => mapPlane(UNIT)),
+ // Its own size, not the others': an effect of Cocos reads positions in the mesh's own space, so the plane it was written against is 10 across.
+ template('cocos-plane', 'Cocos Plane', 'The ground square of Cocos Creator: 10 units across in XZ, facing up, the v of its texture running along +z as a map\'s does.', false,
+ () => cocosPlane(10)),
template('quad', 'Quad', `A ${UNIT}-unit square in XY, facing the camera.`, false,
() => quad(UNIT)),
];
diff --git a/sdk/tests/builtin-meshes.test.ts b/sdk/tests/builtin-meshes.test.ts
index dc59cfe8c..d2f109c7a 100644
--- a/sdk/tests/builtin-meshes.test.ts
+++ b/sdk/tests/builtin-meshes.test.ts
@@ -38,7 +38,7 @@ const cross = (a: Vec, b: Vec): Vec => ({
describe('built-in meshes', () => {
it('offers every primitive under a builtin: ref', () => {
expect(BUILTIN_MESH_TEMPLATES.map((t) => t.id).sort())
- .toEqual(['capsule', 'cone', 'cube', 'cylinder', 'map-plane', 'plane', 'quad', 'sphere']);
+ .toEqual(['capsule', 'cocos-plane', 'cone', 'cube', 'cylinder', 'plane', 'quad', 'sphere']);
for (const t of BUILTIN_MESH_TEMPLATES) {
expect(t.ref).toBe(`builtin:${t.id}`);
expect(isBuiltinMeshRef(t.ref)).toBe(true);
@@ -47,7 +47,7 @@ describe('built-in meshes', () => {
});
// A texture over the plane of Cocos reads as a map seen from above, v running towards +z; the engine's own plane runs it the other way.
- it('runs the v of the map plane along +z and the v of the plane the other way', () => {
+ it('runs the v of the Cocos plane along +z and the v of the plane the other way', () => {
const vOf = (id: string, z: number): number => {
const mesh = builtinMeshTemplate(`builtin:${id}`)!.build();
const view = new DataView(mesh.vertices.buffer, mesh.vertices.byteOffset, mesh.vertices.byteLength);
@@ -59,8 +59,8 @@ describe('built-in meshes', () => {
}
throw new Error('no vertex there');
};
- expect(vOf('map-plane', -50)).toBeCloseTo(0, 5);
- expect(vOf('map-plane', 50)).toBeCloseTo(1, 5);
+ expect(vOf('cocos-plane', -5)).toBeCloseTo(0, 5);
+ expect(vOf('cocos-plane', 5)).toBeCloseTo(1, 5);
expect(vOf('plane', -50)).toBeCloseTo(1, 5);
expect(vOf('plane', 50)).toBeCloseTo(0, 5);
});
@@ -116,15 +116,17 @@ describe('built-in meshes', () => {
}
});
- it('builds each primitive 100 units across, centred on the origin', () => {
+ // The plane of Cocos is the one exception: it stands for what a Cocos effect reads in the mesh's own space, and that plane is 10 across.
+ it('builds each primitive 100 units across, centred on the origin, and the Cocos plane 10', () => {
for (const t of BUILTIN_MESH_TEMPLATES) {
const mesh = t.build();
+ const across = t.id === 'cocos-plane' ? 10 : 100;
for (let k = 0; k < 3; k++) {
expect(mesh.aabbMin[k]).toBeCloseTo(-mesh.aabbMax[k]!, 4);
- expect(mesh.aabbMax[k]).toBeLessThanOrEqual(50.0001);
+ expect(mesh.aabbMax[k]).toBeLessThanOrEqual(across / 2 + 0.0001);
}
const size = Math.max(...mesh.aabbMax.map((v, k) => v - mesh.aabbMin[k]!));
- expect(size).toBeCloseTo(100, 4);
+ expect(size).toBeCloseTo(across, 4);
}
});
});