Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
24 commits
Select commit Hold shift + click to select a range
f9073d0
feat(core): expand primitive mesh creation
GuoLei1990 Nov 14, 2026
121dd6f
refactor(core): simplify extrusion options
GuoLei1990 Nov 14, 2026
2d809e6
refactor(core): require primitive shape inputs
GuoLei1990 Nov 14, 2026
807bab5
refactor(core): clarify primitive parameter names
GuoLei1990 Nov 14, 2026
3e253f5
refactor(core): clarify extruded polygon creation
GuoLei1990 Nov 14, 2026
026ffa2
chore: restore repository license
GuoLei1990 Nov 14, 2026
6f95546
perf(core): avoid default primitive option allocations
GuoLei1990 Nov 14, 2026
224f73a
refactor(core): separate extrusion overload contracts
GuoLei1990 Nov 14, 2026
50f7db2
refactor(core): use standard primitive tangent initialization
GuoLei1990 Nov 14, 2026
eaa71d2
docs(core): tighten tangent comments
GuoLei1990 Nov 14, 2026
309f902
test(core): cover vertex buffer listener lifecycle
GuoLei1990 Nov 14, 2026
75bf822
refactor(core): remove redundant mesh checks
GuoLei1990 Nov 14, 2026
43850cb
refactor(loader): derive serialized primitive shapes
GuoLei1990 Nov 14, 2026
cf1a786
refactor(loader): inline serialized polygon types
GuoLei1990 Nov 14, 2026
57ee677
perf(loader): avoid unnecessary primitive option copies
GuoLei1990 Nov 14, 2026
5ba172b
refactor(loader): clarify primitive parser input types
GuoLei1990 Nov 14, 2026
7b40aeb
fix(core): preserve non-indexed primitive restoration
GuoLei1990 Nov 14, 2026
032c33a
test(e2e): refresh primitive rendering baselines
GuoLei1990 Nov 14, 2026
763c502
fix(core): preserve cylinder texture and cap ordering
GuoLei1990 Nov 14, 2026
3f37ca6
refactor(core): align mesh data retention option naming
GuoLei1990 Nov 14, 2026
0852112
fix(core): simplify primitive restoration and mesh edge cases
GuoLei1990 Nov 14, 2026
8b635f8
docs: clarify primitive mesh usage and script guidance
GuoLei1990 Nov 15, 2026
b07f252
docs: clarify engine script knowledge boundaries
GuoLei1990 Nov 15, 2026
d145696
refactor(core): name revolved surface creation explicitly
GuoLei1990 Nov 15, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions docs/en/graphics/background/sky.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -43,13 +43,13 @@ Procedural sky is the default background in 3D projects in the editor. You can a
### Code to Set Procedural Sky

```typescript
// 创建大气散射材质
// Create the atmospheric scattering material
const skyMaterial = new SkyProceduralMaterial(engine);
// 设置天空盒
// Set the procedural sky background
const background = scene.background;
background.mode = BackgroundMode.Sky;
background.sky.material = skyMaterial;
background.sky.mesh = PrimitiveMesh.createSphere(engine);
background.sky.mesh = PrimitiveMesh.createSphere(engine, 0.5);
```

### Properties
Expand Down
265 changes: 254 additions & 11 deletions docs/en/graphics/mesh/primitiveMesh.mdx

Large diffs are not rendered by default.

4 changes: 2 additions & 2 deletions docs/zh/graphics/background/sky.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -45,11 +45,11 @@ label: Graphics/Background
```typescript
// 创建大气散射材质
const skyMaterial = new SkyProceduralMaterial(engine);
// 设置天空盒
// 设置程序化天空背景
const background = scene.background;
background.mode = BackgroundMode.Sky;
background.sky.material = skyMaterial;
background.sky.mesh = PrimitiveMesh.createSphere(engine);
background.sky.mesh = PrimitiveMesh.createSphere(engine, 0.5);
```

### 属性
Expand Down
275 changes: 262 additions & 13 deletions docs/zh/graphics/mesh/primitiveMesh.mdx

Large diffs are not rendered by default.

188 changes: 188 additions & 0 deletions e2e/case/.primitiveMeshGallery.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,188 @@
import {
BlinnPhongMaterial,
Camera,
DirectLight,
Entity,
Font,
MeshRenderer,
MeshTopology,
ModelMesh,
TextRenderer,
Texture2D,
TextureFilterMode,
TextureFormat,
UnlitMaterial,
Vector3,
WebGLEngine
} from "@galacean/engine";
import { initScreenshot, updateForE2E } from "./.mockForE2E";

export interface PrimitiveMeshExample {
label: string;
detail: string;
mesh: ModelMesh;
rotation?: Vector3;
wireframe?: boolean;
appearance?: "checker" | "solid" | "groups";
}

/**
* Shared presentation for the primitive mesh visual regression cases.
*/
export class PrimitiveMeshGallery {
private readonly _root: Entity;
private readonly _camera: Camera;
private readonly _font: Font;

constructor(readonly engine: WebGLEngine) {
const scene = engine.sceneManager.activeScene!;
scene.background.solidColor.set(0.035, 0.045, 0.065, 1);
scene.ambientLight.diffuseSolidColor.set(0.3, 0.3, 0.3, 1);
this._root = scene.createRootEntity("Primitive features");
const cameraEntity = this._root.createChild("Camera");
cameraEntity.transform.setPosition(0, 0, 30);
this._camera = cameraEntity.addComponent(Camera);
this._camera.isOrthographic = true;
this._camera.farClipPlane = 100;
const light = this._root.createChild("Light");
light.transform.setRotation(35, -35, 0);
light.addComponent(DirectLight).color.set(0.8, 0.8, 0.8, 1);
this._font = Font.createFromOS(engine, "AlibabaSans")!;
}

static async create(): Promise<PrimitiveMeshGallery> {
await document.fonts.load('26px "AlibabaSans"');
const engine = await WebGLEngine.create({ canvas: "canvas" });
engine.canvas.setAutoResolution(2);
return new PrimitiveMeshGallery(engine);
}

show(title: string, examples: PrimitiveMeshExample[], columns: number): void {
const rows = Math.ceil(examples.length / columns);
this._camera.orthographicSize = Math.max((rows * 3.3) / 2 + 1, (columns * 3.5) / 3 + 0.1);
const checker = new BlinnPhongMaterial(this.engine);
checker.baseTexture = this._createChecker();
checker.specularColor.set(0.15, 0.15, 0.15, 1);
const solid = new BlinnPhongMaterial(this.engine);
solid.baseColor.set(0.45, 0.69, 0.85, 1);
solid.specularColor.set(0.15, 0.15, 0.15, 1);
const wire = new UnlitMaterial(this.engine);
wire.baseColor.set(0.025, 0.07, 0.1, 1);
wire.isTransparent = true;
const groupColors = [
[0.3, 0.65, 0.95],
[1, 0.65, 0.25],
[0.55, 0.85, 0.45],
[0.95, 0.4, 0.5],
[0.75, 0.5, 0.95],
[0.3, 0.85, 0.8]
];
const groups = groupColors.map(([r, g, b]) => {
const material = solid.clone();
material.baseColor.set(r, g, b, 1);
return material;
});

this._createLabel(title, 0, ((rows - 1) / 2) * 3.3 + 1.85, 34);
examples.forEach(({ label, detail, mesh, rotation, wireframe, appearance = "checker" }, index) => {
const { min, max } = mesh.bounds;
if (mesh.vertexCount === 0 || ![min.x, min.y, min.z, max.x, max.y, max.z].every(Number.isFinite)) {
throw new Error(`Invalid primitive in gallery: ${label}`);
}
const row = Math.floor(index / columns);
const rowColumns = Math.min(columns, examples.length - row * columns);
const x = ((index % columns) - (rowColumns - 1) / 2) * 3.5;
const y = ((rows - 1) / 2 - row) * 3.3;
const pivot = this._root.createChild(label);
pivot.transform.setPosition(x, y + 0.25, 0);
pivot.transform.rotation = rotation ?? new Vector3(22, -28, 0);
const scale = 1.7 / Math.max(max.x - min.x, max.y - min.y, max.z - min.z);
pivot.transform.setScale(scale, scale, scale);
const entity = pivot.createChild("Surface");
entity.transform.setPosition(-(min.x + max.x) / 2, -(min.y + max.y) / 2, -(min.z + max.z) / 2);
const renderer = entity.addComponent(MeshRenderer);
renderer.mesh = mesh;
renderer.setMaterials(
mesh.subMeshes.map((_, slot) =>
wireframe
? solid
: appearance === "groups"
? groups[slot % groups.length]
: appearance === "solid"
? solid
: checker
)
);
if (wireframe) {
const lines = entity.createChild("Triangle edges").addComponent(MeshRenderer);
lines.mesh = this._createWireframe(mesh);
lines.setMaterial(wire);
}
this._createLabel(label, x, y - 1.1, 26);
this._createLabel(detail, x, y - 1.45, 19);
});
updateForE2E(this.engine);
initScreenshot(this.engine, this._camera, 1800, Math.max(1200, rows * 300));
}

private _createWireframe(mesh: ModelMesh): ModelMesh {
const indices = mesh.getIndices()!;
const lines: number[] = [];
const edges = new Set<string>();
for (let i = 0; i < indices.length; i += 3) {
for (let edge = 0; edge < 3; edge++) {
const a = indices[i + edge];
const b = indices[i + ((edge + 1) % 3)];
const key = `${Math.min(a, b)}:${Math.max(a, b)}`;
if (!edges.has(key)) {
edges.add(key);
lines.push(a, b);
}
}
}
const wireframe = new ModelMesh(this.engine);
const normals = mesh.getNormals()!;
const { min, max } = mesh.bounds;
const offset = Math.max(max.x - min.x, max.y - min.y, max.z - min.z) * 0.001;
wireframe.setPositions(
mesh.getPositions()!.map((point, index) => {
const normal = normals[index];
return new Vector3(point.x + normal.x * offset, point.y + normal.y * offset, point.z + normal.z * offset);
})
);
wireframe.setIndices(new Uint32Array(lines));
wireframe.addSubMesh(0, lines.length, MeshTopology.Lines);
wireframe.bounds.min.copyFrom(mesh.bounds.min);
wireframe.bounds.max.copyFrom(mesh.bounds.max);
wireframe.uploadData(true);
return wireframe;
}

private _createChecker(): Texture2D {
const size = 64;
const pixels = new Uint8Array(size * size * 4);
for (let y = 0; y < size; y++) {
for (let x = 0; x < size; x++) {
const dark = ((x >> 3) + (y >> 3)) % 2 === 0;
const color = x < 2 ? [240, 82, 85] : y < 2 ? [246, 187, 62] : dark ? [40, 110, 165] : [225, 238, 248];
const offset = (y * size + x) * 4;
pixels.set([...color, 255], offset);
}
}
const texture = new Texture2D(this.engine, size, size, TextureFormat.R8G8B8A8, true);
texture.setPixelBuffer(pixels);
texture.generateMipmaps();
texture.filterMode = TextureFilterMode.Trilinear;
return texture;
}

private _createLabel(text: string, x: number, y: number, fontSize: number): void {
const entity = this._root.createChild(text);
entity.transform.setPosition(x, y, 0);
const renderer = entity.addComponent(TextRenderer);
renderer.font = this._font;
renderer.fontSize = fontSize;
renderer.text = text;
renderer.color.set(0.86, 0.91, 0.98, 1);
}
}
6 changes: 3 additions & 3 deletions e2e/case/camera-ssao.ts
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ WebGLEngine.create({
sphere.transform.setPosition(0, 1, 0);
sphere.transform.setRotation(45, 45, 0);
const meshRenderer = sphere.addComponent(MeshRenderer);
meshRenderer.mesh = PrimitiveMesh.createSubdivisionSurfaceSphere(engine);
meshRenderer.mesh = PrimitiveMesh.createSphere(engine, 0.5);
meshRenderer.setMaterial(sphereMaterial);

// Box
Expand All @@ -71,7 +71,7 @@ WebGLEngine.create({
box.transform.setPosition(1, 0.9, 0.1);
box.transform.setRotation(30, 30, 0);
const boxMeshRenderer = box.addComponent(MeshRenderer);
boxMeshRenderer.mesh = PrimitiveMesh.createCuboid(engine);
boxMeshRenderer.mesh = PrimitiveMesh.createCuboid(engine, 1, 1, 1);
boxMeshRenderer.setMaterial(boxMaterial);

// Capsule (transparent)
Expand All @@ -83,7 +83,7 @@ WebGLEngine.create({
capsule.transform.setPosition(1, 0.9, 0.1);
capsule.transform.setRotation(30, 30, 0);
const capsuleMeshRenderer = capsule.addComponent(MeshRenderer);
capsuleMeshRenderer.mesh = PrimitiveMesh.createCapsule(engine);
capsuleMeshRenderer.mesh = PrimitiveMesh.createCapsule(engine, 0.5, 2);
capsuleMeshRenderer.setMaterial(capsuleMaterial);

engine.resourceManager
Expand Down
4 changes: 2 additions & 2 deletions e2e/case/canvas-transparency.ts
Original file line number Diff line number Diff line change
Expand Up @@ -111,7 +111,7 @@ function createMainScene(engine: Engine, transparencyTexture: Texture2D): Textur
planeEntity.transform.setPosition(0, 0, 0);
planeEntity.transform.rotate(new Vector3(90, 0, 0));
const planeRenderer = planeEntity.addComponent(MeshRenderer);
planeRenderer.mesh = PrimitiveMesh.createPlane(engine, 1);
planeRenderer.mesh = PrimitiveMesh.createPlane(engine, 1, 1);

const planeMaterial = new UnlitMaterial(engine);
planeMaterial.baseTexture = transparencyTexture;
Expand All @@ -124,7 +124,7 @@ function createMainScene(engine: Engine, transparencyTexture: Texture2D): Textur
cubeEntity.transform.setPosition(-1, 0, 0);
cubeEntity.transform.rotate(new Vector3(0, 0, 15));
const sphereRenderer = cubeEntity.addComponent(MeshRenderer);
sphereRenderer.mesh = PrimitiveMesh.createCuboid(engine, 1);
sphereRenderer.mesh = PrimitiveMesh.createCuboid(engine, 1, 1, 1);

const sphereMaterial = new UnlitMaterial(engine);
sphereRenderer.setMaterial(sphereMaterial);
Expand Down
2 changes: 1 addition & 1 deletion e2e/case/material-white-furnace.ts
Original file line number Diff line number Diff line change
Expand Up @@ -95,7 +95,7 @@ WebGLEngine.create({ canvas: "canvas" }).then((engine) => {
entity.transform.setPosition(col * spacing - offsetX, (rows - 1 - row) * spacing - offsetY, 0);

const renderer = entity.addComponent(MeshRenderer);
renderer.mesh = PrimitiveMesh.createSphere(engine, 0.5, 32);
renderer.mesh = PrimitiveMesh.createSphere(engine, 0.5, { subdivisionLevel: 4 });

const material = new PBRMaterial(engine);
material.baseColor = rowConfigs[row].baseColor;
Expand Down
4 changes: 2 additions & 2 deletions e2e/case/multi-camera-no-clear.ts
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ function initFirstScene(engine: Engine): Scene {
const cubeEntity = rootEntity.createChild("cube");
cubeEntity.transform.setPosition(-3, 0, 3);
const renderer = cubeEntity.addComponent(MeshRenderer);
renderer.mesh = PrimitiveMesh.createSphere(engine, 2, 24);
renderer.mesh = PrimitiveMesh.createSphere(engine, 2, { subdivisionLevel: 3 });
const material = new BlinnPhongMaterial(engine);
material.baseColor = new Color(1, 0, 0, 1);
renderer.setMaterial(material);
Expand Down Expand Up @@ -83,7 +83,7 @@ function initFirstScene(engine: Engine): Scene {
cubeEntity.layer = Layer.Layer1;
cubeEntity.transform.setPosition(-2, 0, 3);
const renderer = cubeEntity.addComponent(MeshRenderer);
renderer.mesh = PrimitiveMesh.createSphere(engine, 2, 24);
renderer.mesh = PrimitiveMesh.createSphere(engine, 2, { subdivisionLevel: 3 });
const material = new BlinnPhongMaterial(engine);
material.baseColor = new Color(1, 0, 0, 1);
material.emissiveColor.set(1, 0, 0, 1);
Expand Down
2 changes: 1 addition & 1 deletion e2e/case/particleRenderer-emit-billboard-stretched.ts
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@ WebGLEngine.create({

function createFireParticle(rootEntity: Entity, engine: Engine, texture: Texture2D, glTFModel: GLTFResource): Entity {
const meshRenderer = rootEntity.createChild("Mesh").addComponent(MeshRenderer);
meshRenderer.mesh = PrimitiveMesh.createCylinder(engine);
meshRenderer.mesh = PrimitiveMesh.createCylinder(engine, 0.5, 2);
const unlitMaterial = new UnlitMaterial(engine);
unlitMaterial.baseTexture = glTFModel.textures[0];
meshRenderer.setMaterial(unlitMaterial);
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@ WebGLEngine.create({

function createFireParticle(rootEntity: Entity, engine: Engine, texture: Texture2D, glTFModel: GLTFResource): Entity {
const meshRenderer = rootEntity.createChild("Mesh").addComponent(MeshRenderer);
meshRenderer.mesh = PrimitiveMesh.createCylinder(engine);
meshRenderer.mesh = PrimitiveMesh.createCylinder(engine, 0.5, 2);
const unlitMaterial = new UnlitMaterial(engine);
unlitMaterial.baseTexture = glTFModel.textures[0];
meshRenderer.setMaterial(unlitMaterial);
Expand All @@ -87,7 +87,7 @@ function createFireParticle(rootEntity: Entity, engine: Engine, texture: Texture

particleRenderer.renderMode = ParticleRenderMode.Mesh;
// particleRenderer.mesh = glTFModel.meshes[0][0];
particleRenderer.mesh = PrimitiveMesh.createCylinder(engine);
particleRenderer.mesh = PrimitiveMesh.createCylinder(engine, 0.5, 2);

const generator = particleRenderer.generator;
generator.useAutoRandomSeed = false;
Expand Down
4 changes: 2 additions & 2 deletions e2e/case/particleRenderer-emit-mesh-cone-scale-3d-rotation.ts
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@ WebGLEngine.create({

function createFireParticle(rootEntity: Entity, engine: Engine, texture: Texture2D, glTFModel: GLTFResource): Entity {
const meshRenderer = rootEntity.createChild("Mesh").addComponent(MeshRenderer);
meshRenderer.mesh = PrimitiveMesh.createCylinder(engine);
meshRenderer.mesh = PrimitiveMesh.createCylinder(engine, 0.5, 2);
const unlitMaterial = new UnlitMaterial(engine);
unlitMaterial.baseTexture = glTFModel.textures[0];
meshRenderer.setMaterial(unlitMaterial);
Expand All @@ -87,7 +87,7 @@ function createFireParticle(rootEntity: Entity, engine: Engine, texture: Texture

particleRenderer.renderMode = ParticleRenderMode.Mesh;
// particleRenderer.mesh = glTFModel.meshes[0][0];
particleRenderer.mesh = PrimitiveMesh.createCylinder(engine);
particleRenderer.mesh = PrimitiveMesh.createCylinder(engine, 0.5, 2);

const generator = particleRenderer.generator;
generator.useAutoRandomSeed = false;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@ WebGLEngine.create({

function createFireParticle(rootEntity: Entity, engine: Engine, texture: Texture2D, glTFModel: GLTFResource): Entity {
const meshRenderer = rootEntity.createChild("Mesh").addComponent(MeshRenderer);
meshRenderer.mesh = PrimitiveMesh.createCylinder(engine);
meshRenderer.mesh = PrimitiveMesh.createCylinder(engine, 0.5, 2);
const unlitMaterial = new UnlitMaterial(engine);
unlitMaterial.baseTexture = glTFModel.textures[0];
meshRenderer.setMaterial(unlitMaterial);
Expand All @@ -87,7 +87,7 @@ function createFireParticle(rootEntity: Entity, engine: Engine, texture: Texture

particleRenderer.renderMode = ParticleRenderMode.Mesh;
// particleRenderer.mesh = glTFModel.meshes[0][0];
particleRenderer.mesh = PrimitiveMesh.createCylinder(engine);
particleRenderer.mesh = PrimitiveMesh.createCylinder(engine, 0.5, 2);

const generator = particleRenderer.generator;
generator.useAutoRandomSeed = false;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@ WebGLEngine.create({

function createFireParticle(rootEntity: Entity, engine: Engine, texture: Texture2D, glTFModel: GLTFResource): Entity {
const meshRenderer = rootEntity.createChild("Mesh").addComponent(MeshRenderer);
meshRenderer.mesh = PrimitiveMesh.createCylinder(engine);
meshRenderer.mesh = PrimitiveMesh.createCylinder(engine, 0.5, 2);
const unlitMaterial = new UnlitMaterial(engine);
unlitMaterial.baseTexture = glTFModel.textures[0];
meshRenderer.setMaterial(unlitMaterial);
Expand All @@ -87,7 +87,7 @@ function createFireParticle(rootEntity: Entity, engine: Engine, texture: Texture

particleRenderer.renderMode = ParticleRenderMode.Mesh;
// particleRenderer.mesh = glTFModel.meshes[0][0];
particleRenderer.mesh = PrimitiveMesh.createCylinder(engine);
particleRenderer.mesh = PrimitiveMesh.createCylinder(engine, 0.5, 2);

const generator = particleRenderer.generator;
generator.useAutoRandomSeed = false;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@ WebGLEngine.create({

function createFireParticle(rootEntity: Entity, engine: Engine, texture: Texture2D, glTFModel: GLTFResource): Entity {
const meshRenderer = rootEntity.createChild("Mesh").addComponent(MeshRenderer);
meshRenderer.mesh = PrimitiveMesh.createCylinder(engine);
meshRenderer.mesh = PrimitiveMesh.createCylinder(engine, 0.5, 2);
const unlitMaterial = new UnlitMaterial(engine);
unlitMaterial.baseTexture = glTFModel.textures[0];
meshRenderer.setMaterial(unlitMaterial);
Expand All @@ -87,7 +87,7 @@ function createFireParticle(rootEntity: Entity, engine: Engine, texture: Texture

particleRenderer.renderMode = ParticleRenderMode.Mesh;
// particleRenderer.mesh = glTFModel.meshes[0][0];
particleRenderer.mesh = PrimitiveMesh.createCylinder(engine);
particleRenderer.mesh = PrimitiveMesh.createCylinder(engine, 0.5, 2);

const generator = particleRenderer.generator;
generator.useAutoRandomSeed = false;
Expand Down
Loading
Loading