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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(cocos): a particle system colour gradient and size curve become the emitter colorGradient and sizeCurve instead of their two ends
yhh8be12b6ec305
diff --git a/pipeline/src/import/cocos/particle.ts b/pipeline/src/import/cocos/particle.tsindex 7330af849..1a4cba06b 100644--- a/pipeline/src/import/cocos/particle.ts+++ b/pipeline/src/import/cocos/particle.ts@@ -4,9 +4,9 @@* @file `cc.ParticleSystem` as the engine's `ParticleEmitter`.** Cocos describes a system as a main block plus optional modules (shape, size/colour/rotation over lifetime, texture animation, ...), each- * value a range that is a constant, two constants, or a curve. The engine's emitter is flatter: one start and one end value per quantity,- * linearly eased. What the two share is mapped; a curve is sampled at its two ends, so a fade that rises and falls keeps only its ends. What- * the engine's emitter has no field for is counted, so the gap is a list.+ * value a range that is a constant, two constants, or a curve. The emitter carries a start and an end value per quantity, and for a+ * colour or size that changes in more than a straight line, an authored gradient (`colorGradient`) or curve (`sizeCurve`) that the sim+ * samples by age. What the emitter has no field for is counted, so the gap is a list.*/import type { CocosAssetEntry } from './assets';import type { ImportReport } from './report';@@ -107,11 +107,52 @@ function gradientRange(v: unknown, t: number): Rgba {const mid = (r: Range): number => (r.min + r.max) / 2;-/** How many distinct keys a gradient has between its ends: the engine's linear start-to-end ease cannot hold them. */-function interiorKeys(g: unknown): number {- if (!isObj(g)) return 0;- const count = (list: unknown): number => (Array.isArray(list) ? list.filter((k) => isObj(k) && num(k.time, 0) > 0.001 && num(k.time, 0) < 0.999).length : 0);- return count(g.colorKeys) + count(g.alphaKeys);+/** The times at which a gradient range changes, ends included, in order. */+function gradientTimes(v: unknown): number[] {+ const times = new Set<number>([0, 1]);+ if (isObj(v)) {+ for (const g of [v.gradient, v.gradientMin]) {+ if (!isObj(g)) continue;+ for (const list of [g.colorKeys, g.alphaKeys]) {+ for (const k of Array.isArray(list) ? list : []) {+ if (isObj(k)) times.add(Math.min(1, Math.max(0, num(k.time, 0))));+ }+ }+ }+ }+ return [...times].sort((a, b) => a - b);+}++/** The colour over a particle's life: the start colour times the over-lifetime gradient, as stops the sim samples by age. */+function colorStops(start: Rgba, over: unknown): Array<{ t: number; color: Raw }> {+ return gradientTimes(over).map((t) => {+ const g = gradientRange(over, t);+ return { t, color: { r: start[0] * g[0], g: start[1] * g[1], b: start[2] * g[2], a: start[3] * g[3] } };+ });+}++/** A size-over-lifetime curve as the engine's keyframes (value times the start size). Two curves are averaged at every key time. */+function sizeKeys(v: unknown): Array<{ time: number; value: number; inTangent: number; outTangent: number }> | null {+ if (!isObj(v)) return null;+ const mode = num(v.mode, 0);+ const mult = num(v.multiplier, 1);+ const read = (spline: unknown): Array<{ time: number; value: number; inTangent: number; outTangent: number }> | null => {+ if (!isObj(spline) || !Array.isArray(spline._values)) return null;+ const keys = spline._values.filter(isObj).map((k) => ({+ time: num(k.time, 0), value: num(k.value, 0) * mult, inTangent: num(k.inTangent, 0) * mult, outTangent: num(k.outTangent, 0) * mult,+ }));+ return keys.length ? keys : null;+ };+ if (mode === 1) return read(v.spline);+ if (mode === 2) {+ const lo = read(v.splineMin);+ const hi = read(v.splineMax);+ if (!lo || !hi) return lo ?? hi;+ const times = [...new Set([...lo, ...hi].map((k) => k.time))].sort((a, b) => a - b);+ return times.map((time) => ({ time, value: (sampleKeys(lo, time) + sampleKeys(hi, time)) / 2, inTangent: 0, outTangent: 0 }));+ }+ const k = mid(curveRange(v, 0, 1));+ return [{ time: 0, value: k, inTangent: 0, outTangent: 0 }, { time: 1, value: k, inTangent: 0, outTangent: 0 }];}/** Cocos's emitter shapes in the engine's numbering. */@@ -152,35 +193,24 @@ export function particleSystem(c: { enabled: boolean; data: Raw }, ctx: Particleif (mid(curveRange(d.startDelay, 0, 0)) > 0) lose('particle-start-delay');if (mid(curveRange(d.rateOverDistance, 0, 0)) > 0) lose('particle-rate-over-distance');- // colour: the start colour, eased to its value at the end of life by the over-lifetime gradient+ // colour: the start colour times the over-lifetime gradient, sampled by ageconst start = gradientRange(d.startColor, 0);- let first: Rgba = [1, 1, 1, 1];- let last: Rgba = [1, 1, 1, 1];const colorModule = isObj(d._colorOverLifetimeModule) && d._colorOverLifetimeModule._enable === true ? d._colorOverLifetimeModule : null;- if (colorModule) {- first = gradientRange(colorModule.color, 0);- last = gradientRange(colorModule.color, 1);- const range = isObj(colorModule.color) ? colorModule.color : {};- if (interiorKeys(range.gradient) + interiorKeys(range.gradientMin) > 0) lose('particle-color-keys');- }- const mul = (a: Rgba, b: Rgba): Raw => ({ r: a[0] * b[0], g: a[1] * b[1], b: a[2] * b[2], a: a[3] * b[3] });- out.startColor = mul(start, first);- out.endColor = mul(start, last);+ const stops = colorStops(start, colorModule?.color);+ out.startColor = stops[0]!.color;+ out.endColor = stops[stops.length - 1]!.color;+ if (colorModule && stops.length > 2) out.colorGradient = { stops };- // size over lifetime scales the start size to the curve's value at the end+ // size over lifetime multiplies the start size by the curve's value at the particle's ageconst sizeModule = isObj(d._sizeOvertimeModule) && d._sizeOvertimeModule._enable === true ? d._sizeOvertimeModule : null;- if (sizeModule) {- const from = mid(curveRange(sizeModule.size, 0, 1));- const to = mid(curveRange(sizeModule.size, 1, 1));- const k = from === 0 ? 1 : to / from;- out.endSizeMin = size.min * k;- out.endSizeMax = size.max * k;- if (isObj(sizeModule.size) && num(sizeModule.size.mode, 0) !== 0 && Math.abs(mid(curveRange(sizeModule.size, 0.5, from)) - (from + to) / 2) > 0.1 * Math.max(Math.abs(from), 0.0001)) {- lose('particle-size-curve');- }- } else {- out.endSizeMin = size.min;- out.endSizeMax = size.max;+ out.endSizeMin = size.min;+ out.endSizeMax = size.max;+ const keys = sizeModule ? sizeKeys(sizeModule.size) : null;+ if (keys) {+ out.sizeCurve = { keys };+ const end = sampleKeys(keys, 1);+ out.endSizeMin = size.min * end;+ out.endSizeMax = size.max * end;}const rotationModule = isObj(d._rotationOvertimeModule) && d._rotationOvertimeModule._enable === true ? d._rotationOvertimeModule : null;diff --git a/pipeline/tests/cocos-particle.test.ts b/pipeline/tests/cocos-particle.test.tsindex 857814f9c..7c58b18b5 100644--- a/pipeline/tests/cocos-particle.test.ts+++ b/pipeline/tests/cocos-particle.test.ts@@ -92,11 +92,16 @@ describe('a particle system', () => {expect([d.startSizeMin, d.endSizeMin]).toEqual([0.6, 0.3]);});- it('counts a fade that rises and falls as partial, since the engine eases between two ends', () => {+ it('keeps a fade that rises and falls as a gradient the sim samples by age, and a size curve as keys', () => {const fade = { _mode: 1, gradient: { colorKeys: [], alphaKeys: [{ time: 0, alpha: 0 }, { time: 0.5, alpha: 255 }, { time: 1, alpha: 0 }] } };- const { report } = convert({ _colorOverLifetimeModule: { _enable: true, color: fade } });- expect(report.components['cc.ParticleSystem']).toEqual({ mapped: 0, partial: 1, unmapped: 0 });- expect(report.notes['particle-color-keys']?.count).toBe(1);+ const swell = curve([[0, 0.2], [0.5, 1], [1, 0.1]]);+ const { out, report } = convert({ _colorOverLifetimeModule: { _enable: true, color: fade }, _sizeOvertimeModule: { _enable: true, size: swell } });+ const d = out.data as Record<string, any>;+ expect(d.colorGradient.stops.map((s: any) => [s.t, Math.round(s.color.a * 100) / 100])).toEqual([[0, 0], [0.5, 1], [1, 0]]);+ expect(d.sizeCurve.keys.map((k: any) => [k.time, k.value])).toEqual([[0, 0.2], [0.5, 1], [1, 0.1]]);+ expect(report.components['cc.ParticleSystem']).toEqual({ mapped: 1, partial: 0, unmapped: 0 });+ const def = registry.ParticleEmitter!;+ expect(validate('ParticleEmitter', def._default, d, def.assetFields)).toEqual([]);});it('counts the modules the emitter has no field for', () => {diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex 17bedcede..5dc32cd34 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 particle system colour gradient and size curve become the emitter colorGradient and sizeCurve instead of their two ends':+ {"internal":"The Cocos Creator compatibility layer and importer have not shipped; nothing a creator reaches without opting in."},'feat(cocos): the importer maps ParticleSystem onto ParticleEmitter, and counts what the emitter has no field for':{"internal":"The Cocos Creator compatibility layer and importer have not shipped; nothing a creator reaches without opting in."},'feat(2d): GroupOpacity fades an entity and everything under it; sprites, text, shapes, trails and tilemap layers multiply the opacities of the groups above them into their own alpha, and the Cocos UIOpacity is a view on it':