@flighthq/particles-formats 0.1.0

package/src/particleDesignerParse.test.ts

@@ -0,0 +1,279 @@
+import { parseParticleDesignerPlist, parseParticleDesignerPlistDocument } from './particleDesignerParse';
+import { serializeParticleDesignerPlist } from './particleDesignerSerialize';
+
+const FIRE_PLIST = `<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>maxParticles</key><integer>200</integer>
+  <key>emitterType</key><integer>0</integer>
+  <key>duration</key><real>-1</real>
+  <key>particleLifespan</key><real>1.5</real>
+  <key>particleLifespanVariance</key><real>0.5</real>
+  <key>speed</key><real>100</real>
+  <key>speedVariance</key><real>20</real>
+  <key>angle</key><real>90</real>
+  <key>angleVariance</key><real>30</real>
+  <key>gravityx</key><real>0</real>
+  <key>gravityy</key><real>200</real>
+  <key>sourcePositionVariancex</key><real>0</real>
+  <key>sourcePositionVariancey</key><real>0</real>
+  <key>startParticleSize</key><real>32</real>
+  <key>startParticleSizeVariance</key><real>8</real>
+  <key>finishParticleSize</key><real>8</real>
+  <key>finishParticleSizeVariance</key><real>0</real>
+  <key>startColorRed</key><real>1</real>
+  <key>startColorGreen</key><real>0.5</real>
+  <key>startColorBlue</key><real>0</real>
+  <key>startColorAlpha</key><real>1</real>
+  <key>startColorVarianceRed</key><real>0</real>
+  <key>startColorVarianceGreen</key><real>0</real>
+  <key>startColorVarianceBlue</key><real>0</real>
+  <key>startColorVarianceAlpha</key><real>0</real>
+  <key>finishColorRed</key><real>1</real>
+  <key>finishColorGreen</key><real>0</real>
+  <key>finishColorBlue</key><real>0</real>
+  <key>finishColorAlpha</key><real>0</real>
+  <key>finishColorVarianceRed</key><real>0</real>
+  <key>finishColorVarianceGreen</key><real>0</real>
+  <key>finishColorVarianceBlue</key><real>0</real>
+  <key>finishColorVarianceAlpha</key><real>0</real>
+  <key>rotationStart</key><real>0</real>
+  <key>rotationStartVariance</key><real>0</real>
+  <key>rotationEnd</key><real>0</real>
+  <key>rotationEndVariance</key><real>0</real>
+  <key>maxRadius</key><real>0</real>
+  <key>maxRadiusVariance</key><real>0</real>
+  <key>minRadius</key><real>0</real>
+  <key>minRadiusVariance</key><real>0</real>
+  <key>rotatePerSecond</key><real>0</real>
+  <key>rotatePerSecondVariance</key><real>0</real>
+  <key>blendFuncSource</key><integer>770</integer>
+  <key>blendFuncDestination</key><integer>771</integer>
+  <key>textureFileName</key><string>fire.png</string>
+</dict>
+</plist>`;
+
+describe('parseParticleDesignerPlist', () => {
+  describe('color variance and blend mode', () => {
+    it('maps startColorVariance fields to colorStartVariance', () => {
+      const plist = FIRE_PLIST.replace(
+        '<key>startColorVarianceRed</key><real>0</real>',
+        '<key>startColorVarianceRed</key><real>0.3</real>',
+      );
+      const c = parseParticleDesignerPlist(plist);
+      expect(c.colorStartVarianceR).toBeCloseTo(0.3);
+    });
+
+    it('maps additive blend func (770, 1) to blendMode="add"', () => {
+      const plist = FIRE_PLIST.replace(
+        '<key>blendFuncDestination</key><integer>771</integer>',
+        '<key>blendFuncDestination</key><integer>1</integer>',
+      );
+      const c = parseParticleDesignerPlist(plist);
+      expect(c.blendMode).toBe('add');
+    });
+
+    it('round-trips color variance through serialize', () => {
+      const modified = FIRE_PLIST.replace(
+        '<key>startColorVarianceGreen</key><real>0</real>',
+        '<key>startColorVarianceGreen</key><real>0.2</real>',
+      );
+      const config = parseParticleDesignerPlist(modified);
+      const { document } = parseParticleDesignerPlistDocument(modified);
+      const xml = serializeParticleDesignerPlist(config, document);
+      const config2 = parseParticleDesignerPlist(xml);
+      expect(config2.colorStartVarianceG).toBeCloseTo(0.2, 3);
+    });
+  });
+
+  describe('lightweight, returns config directly', () => {
+    it('returns a ParticleEmitterConfig (not a Parsed object)', () => {
+      const result = parseParticleDesignerPlist(FIRE_PLIST);
+      expect(typeof result.maxParticles).toBe('number');
+      expect((result as unknown as Record<string, unknown>).document).toBeUndefined();
+    });
+
+    it('parses maxParticles', () => {
+      expect(parseParticleDesignerPlist(FIRE_PLIST).maxParticles).toBe(200);
+    });
+
+    it('converts lifetime with variance to min/max', () => {
+      const c = parseParticleDesignerPlist(FIRE_PLIST);
+      expect(c.lifetimeMin).toBeCloseTo(1.0);
+      expect(c.lifetimeMax).toBeCloseTo(2.0);
+    });
+
+    it('converts speed with variance to min/max', () => {
+      const c = parseParticleDesignerPlist(FIRE_PLIST);
+      expect(c.speedMin).toBeCloseTo(80);
+      expect(c.speedMax).toBeCloseTo(120);
+    });
+
+    it('maps angle=90 to upward direction (−Y screen)', () => {
+      const c = parseParticleDesignerPlist(FIRE_PLIST);
+      expect(c.directionX).toBeCloseTo(0, 3);
+      expect(c.directionY).toBeCloseTo(-1, 3);
+    });
+
+    it('converts angleVariance to spread in radians', () => {
+      expect(parseParticleDesignerPlist(FIRE_PLIST).spread).toBeCloseTo((30 * Math.PI) / 180, 4);
+    });
+
+    it('maps gravity directly', () => {
+      const c = parseParticleDesignerPlist(FIRE_PLIST);
+      expect(c.gravityX).toBeCloseTo(0);
+      expect(c.gravityY).toBeCloseTo(200);
+    });
+
+    it('maps color start and end', () => {
+      const c = parseParticleDesignerPlist(FIRE_PLIST);
+      expect(c.colorStartR).toBeCloseTo(1);
+      expect(c.colorStartG).toBeCloseTo(0.5);
+      expect(c.colorStartB).toBeCloseTo(0);
+      expect(c.colorEndR).toBeCloseTo(1);
+      expect(c.colorEndG).toBeCloseTo(0);
+      expect(c.colorEndB).toBeCloseTo(0);
+    });
+
+    it('maps alpha start and end', () => {
+      const c = parseParticleDesignerPlist(FIRE_PLIST);
+      expect(c.alphaStart).toBeCloseTo(1);
+      expect(c.alphaEnd).toBeCloseTo(0);
+    });
+
+    it('normalises scale by textureSize', () => {
+      const c = parseParticleDesignerPlist(FIRE_PLIST, { textureSize: 32 });
+      expect(c.scaleMin).toBeCloseTo(0.75);
+      expect(c.scaleMax).toBeCloseTo(1.25);
+    });
+
+    it('computes scaleEnd as finishSize / startSize', () => {
+      const c = parseParticleDesignerPlist(FIRE_PLIST, { textureSize: 32 });
+      expect(c.scaleEnd).toBeCloseTo(0.25);
+    });
+
+    it('uses point emitter shape when sourcePositionVariance is zero', () => {
+      expect(parseParticleDesignerPlist(FIRE_PLIST).emitterShape).toBe('point');
+    });
+
+    it('maps duration=-1 to an infinite (looping) emitter', () => {
+      const c = parseParticleDesignerPlist(FIRE_PLIST);
+      expect(c.loop).toBe(true);
+      expect(c.duration).toBe(0);
+    });
+
+    it('maps a positive duration to a finite, non-looping emitter', () => {
+      const plist = FIRE_PLIST.replace('<key>duration</key><real>-1</real>', '<key>duration</key><real>2.5</real>');
+      const c = parseParticleDesignerPlist(plist);
+      expect(c.loop).toBe(false);
+      expect(c.duration).toBeCloseTo(2.5);
+    });
+  });
+
+  describe('malformed input', () => {
+    it('falls back to defaults (not NaN) for empty numeric tags', () => {
+      const xml =
+        '<plist><dict>' +
+        '<key>maxParticles</key><integer></integer>' +
+        '<key>speed</key><real></real>' +
+        '</dict></plist>';
+      const c = parseParticleDesignerPlist(xml);
+      expect(c.maxParticles).toBe(200); // default, not NaN-coerced 0
+      expect(Number.isFinite(c.speedMin)).toBe(true);
+      expect(Number.isFinite(c.speedMax)).toBe(true);
+    });
+
+    it('returns an all-defaults config for empty/garbage input without throwing', () => {
+      expect(() => parseParticleDesignerPlist('')).not.toThrow();
+      const c = parseParticleDesignerPlist('not xml at all');
+      expect(Number.isFinite(c.maxParticles)).toBe(true);
+      expect(Number.isFinite(c.gravityY)).toBe(true);
+    });
+  });
+});
+
+describe('parseParticleDesignerPlistDocument', () => {
+  describe('full round-trip, returns { config, document }', () => {
+    it('returns the same config values as parseParticleDesignerPlist', () => {
+      const config = parseParticleDesignerPlist(FIRE_PLIST, { textureSize: 32 });
+      const { config: loadedConfig } = parseParticleDesignerPlistDocument(FIRE_PLIST, { textureSize: 32 });
+      expect(loadedConfig.maxParticles).toBe(config.maxParticles);
+      expect(loadedConfig.directionY).toBeCloseTo(config.directionY, 5);
+      expect(loadedConfig.gravityY).toBeCloseTo(config.gravityY, 5);
+    });
+
+    it('preserves textureFileName in document', () => {
+      expect(parseParticleDesignerPlistDocument(FIRE_PLIST).document.textureFileName).toBe('fire.png');
+    });
+
+    it('preserves blend function in document', () => {
+      const { document } = parseParticleDesignerPlistDocument(FIRE_PLIST);
+      expect(document.blendFuncSource).toBe(770);
+      expect(document.blendFuncDestination).toBe(771);
+    });
+  });
+
+  describe('import warnings', () => {
+    it('has no warnings for a standard gravity emitter', () => {
+      expect(parseParticleDesignerPlistDocument(FIRE_PLIST).warnings).toEqual([]);
+    });
+
+    it('warns that a radial emitter is approximated', () => {
+      const plist = FIRE_PLIST.replace(
+        '<key>emitterType</key><integer>0</integer>',
+        '<key>emitterType</key><integer>1</integer>',
+      );
+      expect(parseParticleDesignerPlistDocument(plist).warnings.some((w) => w.toLowerCase().includes('radial'))).toBe(
+        true,
+      );
+    });
+
+    it('warns about unsupported radial/tangential acceleration', () => {
+      const plist = FIRE_PLIST.replace(
+        '<key>maxParticles</key><integer>200</integer>',
+        '<key>maxParticles</key><integer>200</integer><key>radialAcceleration</key><real>50</real>',
+      );
+      expect(parseParticleDesignerPlistDocument(plist).warnings.some((w) => w.includes('radialAcceleration'))).toBe(
+        true,
+      );
+    });
+  });
+});
+
+describe('serializeParticleDesignerPlist', () => {
+  it('round-trips key config fields', () => {
+    const config = parseParticleDesignerPlist(FIRE_PLIST, { textureSize: 32 });
+    const { document } = parseParticleDesignerPlistDocument(FIRE_PLIST, { textureSize: 32 });
+    const xml = serializeParticleDesignerPlist(config, document, { textureSize: 32 });
+    const config2 = parseParticleDesignerPlist(xml, { textureSize: 32 });
+    expect(config2.maxParticles).toBe(config.maxParticles);
+    expect(config2.directionX).toBeCloseTo(config.directionX, 3);
+    expect(config2.gravityY).toBeCloseTo(config.gravityY, 1);
+    expect(config2.colorStartR).toBeCloseTo(config.colorStartR, 3);
+    expect(config2.alphaEnd).toBeCloseTo(config.alphaEnd, 3);
+  });
+
+  it('preserves textureFileName', () => {
+    const config = parseParticleDesignerPlist(FIRE_PLIST);
+    const { document } = parseParticleDesignerPlistDocument(FIRE_PLIST);
+    expect(serializeParticleDesignerPlist(config, document)).toContain('fire.png');
+  });
+
+  it('produces valid plist XML', () => {
+    const config = parseParticleDesignerPlist(FIRE_PLIST);
+    const xml = serializeParticleDesignerPlist(config);
+    expect(xml).toContain('<?xml version="1.0"');
+    expect(xml).toContain('<plist version="1.0">');
+  });
+
+  it('escapes XML special characters in the texture filename and round-trips them', () => {
+    const config = parseParticleDesignerPlist(FIRE_PLIST);
+    const xml = serializeParticleDesignerPlist(config, { textureFileName: 'a&b<c>.png' });
+    // Raw special characters must not appear unescaped (would be invalid XML).
+    expect(xml).not.toContain('a&b<c>');
+    expect(xml).toContain('&amp;');
+    // ...and the original value survives a parse round-trip intact.
+    expect(parseParticleDesignerPlistDocument(xml).document.textureFileName).toBe('a&b<c>.png');
+  });
+});

package/src/particleDesignerSerialize.test.ts

@@ -0,0 +1,113 @@
+import { createParticleEmitterConfig } from '@flighthq/particles';
+
+import { parseParticleDesignerPlist, parseParticleDesignerPlistDocument } from './particleDesignerParse';
+import { serializeParticleDesignerPlist, serializeParticleDesignerPlistDocument } from './particleDesignerSerialize';
+
+const FIRE_PLIST = `<?xml version="1.0" encoding="utf-8"?>
+<plist version="1.0">
+<dict>
+  <key>maxParticles</key><integer>200</integer>
+  <key>emitterType</key><integer>0</integer>
+  <key>duration</key><real>-1</real>
+  <key>particleLifespan</key><real>1.5</real>
+  <key>particleLifespanVariance</key><real>0.5</real>
+  <key>speed</key><real>100</real>
+  <key>speedVariance</key><real>20</real>
+  <key>angle</key><real>90</real>
+  <key>angleVariance</key><real>30</real>
+  <key>gravityx</key><real>0</real>
+  <key>gravityy</key><real>200</real>
+  <key>sourcePositionVariancex</key><real>0</real>
+  <key>sourcePositionVariancey</key><real>0</real>
+  <key>startParticleSize</key><real>32</real>
+  <key>startParticleSizeVariance</key><real>8</real>
+  <key>finishParticleSize</key><real>8</real>
+  <key>finishParticleSizeVariance</key><real>0</real>
+  <key>startColorRed</key><real>1</real>
+  <key>startColorGreen</key><real>0.5</real>
+  <key>startColorBlue</key><real>0</real>
+  <key>startColorAlpha</key><real>1</real>
+  <key>startColorVarianceRed</key><real>0</real>
+  <key>startColorVarianceGreen</key><real>0</real>
+  <key>startColorVarianceBlue</key><real>0</real>
+  <key>startColorVarianceAlpha</key><real>0</real>
+  <key>finishColorRed</key><real>1</real>
+  <key>finishColorGreen</key><real>0</real>
+  <key>finishColorBlue</key><real>0</real>
+  <key>finishColorAlpha</key><real>0</real>
+  <key>finishColorVarianceRed</key><real>0</real>
+  <key>finishColorVarianceGreen</key><real>0</real>
+  <key>finishColorVarianceBlue</key><real>0</real>
+  <key>finishColorVarianceAlpha</key><real>0</real>
+  <key>rotationStart</key><real>0</real>
+  <key>rotationStartVariance</key><real>0</real>
+  <key>rotationEnd</key><real>0</real>
+  <key>rotationEndVariance</key><real>0</real>
+  <key>maxRadius</key><real>0</real>
+  <key>maxRadiusVariance</key><real>0</real>
+  <key>minRadius</key><real>0</real>
+  <key>minRadiusVariance</key><real>0</real>
+  <key>rotatePerSecond</key><real>0</real>
+  <key>rotatePerSecondVariance</key><real>0</real>
+  <key>blendFuncSource</key><integer>770</integer>
+  <key>blendFuncDestination</key><integer>771</integer>
+  <key>textureFileName</key><string>fire.png</string>
+</dict>
+</plist>`;
+
+describe('serializeParticleDesignerPlist', () => {
+  it('produces valid plist XML with required structure', () => {
+    const config = parseParticleDesignerPlist(FIRE_PLIST);
+    const xml = serializeParticleDesignerPlist(config);
+    expect(xml).toContain('<?xml version="1.0"');
+    expect(xml).toContain('<plist version="1.0">');
+    expect(xml).toContain('<dict>');
+  });
+
+  it('preserves textureFileName from existing document', () => {
+    const config = parseParticleDesignerPlist(FIRE_PLIST);
+    const { document } = parseParticleDesignerPlistDocument(FIRE_PLIST);
+    expect(serializeParticleDesignerPlist(config, document)).toContain('fire.png');
+  });
+
+  it('round-trips key config fields through parse → serialize → parse', () => {
+    const config = parseParticleDesignerPlist(FIRE_PLIST, { textureSize: 32 });
+    const { document } = parseParticleDesignerPlistDocument(FIRE_PLIST, { textureSize: 32 });
+    const xml = serializeParticleDesignerPlist(config, document, { textureSize: 32 });
+    const config2 = parseParticleDesignerPlist(xml, { textureSize: 32 });
+    expect(config2.maxParticles).toBe(config.maxParticles);
+    expect(config2.directionX).toBeCloseTo(config.directionX, 3);
+    expect(config2.gravityY).toBeCloseTo(config.gravityY, 1);
+  });
+
+  it('escapes XML special characters in the texture filename', () => {
+    const config = parseParticleDesignerPlist(FIRE_PLIST);
+    const xml = serializeParticleDesignerPlist(config, { textureFileName: 'a&b<c>.png' });
+    expect(xml).not.toContain('a&b<c>');
+    expect(xml).toContain('&amp;');
+  });
+});
+
+describe('serializeParticleDesignerPlistDocument', () => {
+  it('returns { text, warnings } for a standard config', () => {
+    const config = parseParticleDesignerPlist(FIRE_PLIST);
+    const result = serializeParticleDesignerPlistDocument(config);
+    expect(typeof result.text).toBe('string');
+    expect(result.text).toContain('<plist version="1.0">');
+    expect(Array.isArray(result.warnings)).toBe(true);
+    expect(result.warnings).toHaveLength(0);
+  });
+
+  it('warns when the config uses unsupported features', () => {
+    const config = createParticleEmitterConfig({ burstCount: 5 });
+    const result = serializeParticleDesignerPlistDocument(config);
+    expect(result.warnings.some((w) => w.toLowerCase().includes('burst'))).toBe(true);
+  });
+
+  it('preserves textureFileName from existing document in the text output', () => {
+    const config = parseParticleDesignerPlist(FIRE_PLIST);
+    const { document } = parseParticleDesignerPlistDocument(FIRE_PLIST);
+    const result = serializeParticleDesignerPlistDocument(config, document);
+    expect(result.text).toContain('fire.png');
+  });
+});

package/src/pixiParse.test.ts

@@ -0,0 +1,131 @@
+import { parsePixiParticle, parsePixiParticleDocument } from './pixiParse';
+
+const FIRE_PIXI = JSON.stringify({
+  alpha: { start: 1, end: 0 },
+  scale: { start: 0.5, end: 1.5, minimumScaleMultiplier: 1 },
+  color: { start: 'ffaa00', end: 'ff0000' },
+  speed: { start: 200, end: 50 },
+  acceleration: { x: 0, y: 0 },
+  maxSpeed: 0,
+  maxParticles: 1000,
+  startRotation: { min: 0, max: 360 },
+  noRotation: false,
+  rotationSpeed: { min: 0, max: 0 },
+  lifetime: { min: 0.5, max: 1.5 },
+  blendMode: 'add',
+  frequency: 0.001,
+  emitterLifetime: -1,
+  pos: { x: 0, y: 0 },
+  addAtBack: false,
+  spawnType: 'point',
+});
+
+const RECT_PIXI = JSON.stringify({
+  alpha: { start: 1, end: 0 },
+  scale: { start: 1, end: 1 },
+  color: { start: 'ffffff', end: 'ffffff' },
+  speed: { start: 100, end: 100 },
+  maxParticles: 200,
+  lifetime: { min: 1, max: 2 },
+  blendMode: 'normal',
+  frequency: 0.01,
+  pos: { x: 0, y: 0 },
+  spawnRect: { x: -50, y: -50, w: 100, h: 100 },
+});
+
+describe('parsePixiParticle', () => {
+  it('returns a ParticleEmitterConfig (not a ParseResult object)', () => {
+    const result = parsePixiParticle(FIRE_PIXI) as unknown as Record<string, unknown>;
+    expect(typeof result.maxParticles).toBe('number');
+    expect(result.warnings).toBeUndefined();
+  });
+  it('parses maxParticles', () => {
+    expect(parsePixiParticle(FIRE_PIXI).maxParticles).toBe(1000);
+  });
+  it('converts frequency to spawnRate', () => {
+    // frequency=0.001 -> spawnRate = 1/0.001 = 1000
+    expect(parsePixiParticle(FIRE_PIXI).spawnRate).toBeCloseTo(1000, 0);
+  });
+  it('maps lifetime to lifetimeMin/Max', () => {
+    const c = parsePixiParticle(FIRE_PIXI);
+    expect(c.lifetimeMin).toBeCloseTo(0.5);
+    expect(c.lifetimeMax).toBeCloseTo(1.5);
+  });
+  it('maps speed start/end to speedMin/Max (sorted)', () => {
+    const c = parsePixiParticle(FIRE_PIXI);
+    // speed start=200, end=50 -> min=50, max=200
+    expect(c.speedMin).toBeCloseTo(50);
+    expect(c.speedMax).toBeCloseTo(200);
+  });
+  it('maps alpha start/end to alphaStart/End', () => {
+    const c = parsePixiParticle(FIRE_PIXI);
+    expect(c.alphaStart).toBeCloseTo(1);
+    expect(c.alphaEnd).toBeCloseTo(0);
+  });
+  it('maps color start/end to colorStart/End', () => {
+    const c = parsePixiParticle(FIRE_PIXI);
+    expect(c.colorStartR).toBeCloseTo(1);
+    expect(c.colorStartG).toBeCloseTo(0xaa / 255, 2);
+    expect(c.colorEndR).toBeCloseTo(1);
+    expect(c.colorEndG).toBeCloseTo(0);
+  });
+  it('maps blendMode="add" to blendMode="add"', () => {
+    expect(parsePixiParticle(FIRE_PIXI).blendMode).toBe('add');
+  });
+  it('maps blendMode="normal" to blendMode="normal"', () => {
+    expect(parsePixiParticle(RECT_PIXI).blendMode).toBe('normal');
+  });
+  it('maps spawnRect to rect emitter shape', () => {
+    const c = parsePixiParticle(RECT_PIXI);
+    expect(c.emitterShape).toBe('rect');
+    expect(c.emitterWidth).toBeCloseTo(100);
+    expect(c.emitterHeight).toBeCloseTo(100);
+  });
+  it('maps spawnCircle to circle emitter shape', () => {
+    const json = JSON.stringify({ ...JSON.parse(FIRE_PIXI), spawnCircle: { x: 0, y: 0, r: 30 } });
+    const c = parsePixiParticle(json);
+    expect(c.emitterShape).toBe('circle');
+    expect(c.emitterRadius).toBeCloseTo(30);
+  });
+  it('maps scale to scaleMin/Max', () => {
+    const c = parsePixiParticle(FIRE_PIXI);
+    // scale start=0.5, end=1.5 -> min=0.5, max=1.5
+    expect(c.scaleMin).toBeCloseTo(0.5);
+    expect(c.scaleMax).toBeCloseTo(1.5);
+  });
+  it('throws a clear, format-tagged error on invalid JSON', () => {
+    expect(() => parsePixiParticle('{not valid')).toThrow(/Invalid Pixi particle JSON/);
+  });
+  it('throws a clear error when the root is not an object', () => {
+    expect(() => parsePixiParticle('null')).toThrow(/expected a JSON object/);
+    expect(() => parsePixiParticle('[1,2]')).toThrow(/expected a JSON object/);
+  });
+  it('falls back to defaults for an empty object without producing NaN', () => {
+    const c = parsePixiParticle('{}');
+    expect(Number.isFinite(c.maxParticles)).toBe(true);
+    expect(Number.isFinite(c.lifetimeMin)).toBe(true);
+  });
+});
+
+describe('parsePixiParticleDocument', () => {
+  it('returns the same config as parsePixiParticle', () => {
+    const config = parsePixiParticle(FIRE_PIXI);
+    const { config: loaded } = parsePixiParticleDocument(FIRE_PIXI);
+    expect(loaded.maxParticles).toBe(config.maxParticles);
+    expect(loaded.speedMax).toBeCloseTo(config.speedMax, 3);
+  });
+  it('has no warnings for a standard point emitter', () => {
+    const { warnings } = parsePixiParticleDocument(FIRE_PIXI);
+    expect(warnings).toEqual([]);
+  });
+  it('warns when acceleration is non-zero', () => {
+    const json = JSON.stringify({ ...JSON.parse(FIRE_PIXI), acceleration: { x: 0, y: 100 } });
+    const { warnings } = parsePixiParticleDocument(json);
+    expect(warnings.some((w) => w.includes('acceleration'))).toBe(true);
+  });
+  it('warns when spawnBurst is present', () => {
+    const json = JSON.stringify({ ...JSON.parse(FIRE_PIXI), spawnBurst: { count: 5, time: 0.5 } });
+    const { warnings } = parsePixiParticleDocument(json);
+    expect(warnings.some((w) => w.includes('spawnBurst'))).toBe(true);
+  });
+});