pixi.js

Version:

pixijs.com

pixijs/pixijs

1 lines • 13.5 kB

Source Map (JSON)

View Raw

{"version":3,"file":"Particle.mjs","sources":["../../../../src/scene/particle-container/shared/Particle.ts"],"sourcesContent":["import { Color } from '../../../color/Color';\nimport { Texture } from '../../../rendering/renderers/shared/texture/Texture';\nimport { bgr2rgb } from '../../container/container-mixins/getGlobalMixin';\nimport { assignWithIgnore } from '../../container/utils/assignWithIgnore';\n\nimport type { ColorSource } from '../../../color/Color';\n\n/**\n * Represents a particle with properties for position, scale, rotation, color, and texture.\n * Particles are lightweight alternatives to sprites, optimized for use in particle systems.\n * @example\n * ```ts\n * // Create a basic particle\n * const particle = new Particle({\n * texture: Texture.from('particle.png'),\n * x: 100,\n * y: 100,\n * scaleX: 0.5,\n * scaleY: 0.5,\n * rotation: Math.PI / 4, // 45 degrees\n * tint: 0xff0000, // Red tint\n * alpha: 0.8 // Slightly transparent\n * });\n *\n * // Modify particle properties\n * particle.x += 10; // Move right\n * particle.rotation += 0.1; // Rotate slightly\n * particle.alpha = 0.5; // Change transparency\n *\n * // Use anchor points (0-1 range)\n * particle.anchorX = 0.5; // Center horizontally\n * particle.anchorY = 0.5; // Center vertically\n * ```\n * @category scene\n * @standard\n */\nexport interface IParticle\n{\n /** The x-coordinate of the particle position */\n x: number;\n\n /** The y-coordinate of the particle position */\n y: number;\n\n /**\n * The horizontal scale factor of the particle\n * @default 1\n */\n scaleX: number;\n\n /**\n * The vertical scale factor of the particle\n * @default 1\n */\n scaleY: number;\n\n /**\n * The x-coordinate of the particle's anchor point (0-1 range)\n * @default 0\n */\n anchorX: number;\n\n /**\n * The y-coordinate of the particle's anchor point (0-1 range)\n * @default 0\n */\n anchorY: number;\n\n /**\n * The rotation of the particle in radians\n * @default 0\n */\n rotation: number;\n\n /**\n * The color of the particle as a 32-bit RGBA value\n * @default 0xffffffff\n */\n color: number;\n\n /** The texture used to render this particle */\n texture: Texture;\n}\n\n/**\n * Configuration options for creating a new particle. All properties except texture are optional\n * and will use default values if not specified.\n * @example\n * ```ts\n * // Create a basic red particle\n * const particle = new Particle({\n * texture: Texture.from('particle.png'),\n * tint: 0xff0000,\n * alpha: 0.8\n * });\n *\n * // Create a scaled and rotated particle\n * const rotatedParticle = new Particle({\n * texture: Texture.from('star.png'),\n * x: 100,\n * y: 100,\n * scaleX: 2,\n * scaleY: 2,\n * rotation: Math.PI / 4,\n * anchorX: 0.5,\n * anchorY: 0.5\n * });\n *\n * // Use color strings for tint\n * const coloredParticle = new Particle({\n * texture: Texture.from('circle.png'),\n * tint: '#ff00ff', // Magenta\n * alpha: 0.5, // Half transparent\n * x: 200,\n * y: 200\n * });\n * ```\n * @see {@link Particle} For the particle implementation\n * @see {@link IParticle} For the full particle interface\n * @category scene\n * @standard\n * @category scene\n * @standard\n */\nexport type ParticleOptions = Omit<Partial<IParticle>, 'color'> & {\n /** The texture used to render this particle */\n texture: Texture;\n /** The tint color as a hex number or CSS color string */\n tint?: ColorSource;\n /** The alpha transparency (0-1) */\n alpha?: number;\n};\n\n/**\n * Represents a single particle within a particle container. This class implements the IParticle interface,\n * providing properties and methods to manage the particle's position, scale, rotation, color, and texture.\n *\n * The reason we use a particle over a sprite is that these are much lighter weight and we can create a lot of them\n * without taking on the overhead of a full sprite.\n * @example\n * ```javascript\n * const particle = new Particle({\n * texture,\n * x: 100,\n * y: 100,\n * scaleX: 0.5,\n * scaleY: 0.5,\n * rotation: Math.PI / 2,\n * color: 0xff0000,\n * });\n * ```\n * @category scene\n * @standard\n */\nexport class Particle implements IParticle\n{\n /**\n * Default options used when creating new particles. These values are applied when specific\n * options aren't provided in the constructor.\n * @example\n * ```ts\n * // Override defaults globally\n * Particle.defaultOptions = {\n * ...Particle.defaultOptions,\n * anchorX: 0.5,\n * anchorY: 0.5,\n * alpha: 0.8\n * };\n *\n * // New particles use modified defaults\n * const centeredParticle = new Particle(texture);\n * console.log(centeredParticle.anchorX); // 0.5\n * console.log(centeredParticle.alpha); // 0.8\n * ```\n * @see {@link ParticleOptions} For all available options\n * @see {@link Particle} For the particle implementation\n */\n public static defaultOptions: Partial<ParticleOptions> = {\n anchorX: 0,\n anchorY: 0,\n x: 0,\n y: 0,\n scaleX: 1,\n scaleY: 1,\n rotation: 0,\n tint: 0xffffff,\n alpha: 1,\n };\n /**\n * The x-coordinate of the anchor point (0-1).\n * Controls the origin point for rotation and scaling.\n * @example\n * ```ts\n * particle.anchorX = 0.5; // Center horizontally\n * ```\n * @default 0\n */\n public anchorX: number;\n\n /**\n * The y-coordinate of the anchor point (0-1).\n * Controls the origin point for rotation and scaling.\n * @example\n * ```ts\n * particle.anchorY = 0.5; // Center vertically\n * ```\n * @default 0\n */\n public anchorY: number;\n\n /**\n * The x-coordinate of the particle in world space.\n * @example\n * ```ts\n * particle.x = 100; // Move right\n * particle.x += Math.sin(time) * 10; // Oscillate horizontally\n * ```\n * @default 0\n */\n public x: number;\n\n /**\n * The y-coordinate of the particle in world space.\n * @example\n * ```ts\n * particle.y = 100; // Move down\n * particle.y += Math.cos(time) * 10; // Oscillate vertically\n * ```\n * @default 0\n */\n public y: number;\n\n /**\n * The horizontal scale factor of the particle.\n * Values greater than 1 increase size, less than 1 decrease size.\n * @example\n * ```ts\n * particle.scaleX = 2; // Double width\n * particle.scaleX *= 0.9; // Shrink over time\n * ```\n * @default 1\n */\n public scaleX: number;\n\n /**\n * The vertical scale factor of the particle.\n * Values greater than 1 increase size, less than 1 decrease size.\n * @example\n * ```ts\n * particle.scaleY = 2; // Double height\n * particle.scaleY *= 0.9; // Shrink over time\n * ```\n * @default 1\n */\n public scaleY: number;\n\n /**\n * The rotation of the particle in radians.\n * Positive values rotate clockwise.\n * @example\n * ```ts\n * particle.rotation = Math.PI; // 180 degrees\n * particle.rotation += 0.1; // Rotate slowly clockwise\n * ```\n * @default 0\n */\n public rotation: number;\n\n /**\n * The color of the particle as a 32-bit RGBA value.\n * Combines tint and alpha into a single value.\n * @example\n * ```ts\n * // Usually set via tint and alpha properties\n * particle.tint = 0xff0000; // Red\n * particle.alpha = 0.5; // Half transparent\n * console.log(particle.color); // Combined RGBA value\n * ```\n * @default 0xffffffff\n */\n public color: number;\n\n /**\n * The texture used to render this particle.\n * All particles in a container should share the same base texture.\n * @example\n * ```ts\n * particle.texture = Texture.from('particle.png');\n * ```\n */\n public texture: Texture;\n\n private _alpha: number;\n private _tint: number;\n\n constructor(options: Texture | ParticleOptions)\n {\n if (options instanceof Texture)\n {\n this.texture = options;\n assignWithIgnore(this, Particle.defaultOptions, {});\n }\n else\n {\n const combined = { ...Particle.defaultOptions, ...options };\n\n assignWithIgnore(this, combined, {});\n }\n }\n\n /**\n * The transparency of the particle. Values range from 0 (fully transparent)\n * to 1 (fully opaque). Values outside this range are clamped.\n * @example\n * ```ts\n * // Create a semi-transparent particle\n * const particle = new Particle({\n * texture: Texture.from('particle.png'),\n * alpha: 0.5\n * });\n *\n * // Fade out\n * particle.alpha *= 0.9;\n *\n * // Fade in\n * particle.alpha = Math.min(particle.alpha + 0.1, 1);\n *\n * // Values are clamped to valid range\n * particle.alpha = 1.5; // Becomes 1.0\n * particle.alpha = -0.5; // Becomes 0.0\n *\n * // Animate transparency\n * app.ticker.add((delta) => {\n * const time = performance.now() / 1000;\n * particle.alpha = 0.5 + Math.sin(time) * 0.5; // Pulse between 0-1\n * });\n * ```\n * @default 1\n * @see {@link Particle#tint} For controlling particle color\n * @see {@link Particle#color} For the combined color and alpha value\n */\n get alpha(): number\n {\n return this._alpha;\n }\n\n set alpha(value: number)\n {\n this._alpha = Math.min(Math.max(value, 0), 1);\n\n this._updateColor();\n }\n\n /**\n * The tint color of the particle. Can be set using hex numbers or CSS color strings.\n * The tint is multiplied with the texture color to create the final particle color.\n * @example\n * ```ts\n * // Create a red particle\n * const particle = new Particle({\n * texture: Texture.from('particle.png'),\n * tint: 0xff0000\n * });\n *\n * // Use CSS color strings\n * particle.tint = '#00ff00'; // Green\n * particle.tint = 'blue'; // Blue\n *\n * // Animate tint color\n * app.ticker.add(() => {\n * const time = performance.now() / 1000;\n *\n * // Cycle through hues\n * const hue = (time * 50) % 360;\n * particle.tint = `hsl(${hue}, 100%, 50%)`;\n * });\n *\n * // Reset to white (no tint)\n * particle.tint = 0xffffff;\n * ```\n * @type {ColorSource} Hex number or CSS color string\n * @default 0xffffff\n * @see {@link Particle#alpha} For controlling transparency\n * @see {@link Particle#color} For the combined color and alpha value\n * @see {@link Color} For supported color formats\n */\n get tint(): number\n {\n return bgr2rgb(this._tint);\n }\n\n set tint(value: ColorSource)\n {\n if (typeof value === 'number')\n {\n this._tint = value;\n }\n else\n {\n this._tint = Color.shared.setValue(value ?? 0xFFFFFF).toBgrNumber();\n }\n\n this._updateColor();\n }\n\n private _updateColor()\n {\n // combine alpha and tint\n this.color = this._tint + (((this._alpha * 255) | 0) << 24);\n }\n}\n"],"names":[],"mappings":";;;;;;AA0JO,MAAM,SAAA,GAAN,MAAM,SACb,CAAA;AAAA,EA4II,YAAY,OACZ,EAAA;AACI,IAAA,IAAI,mBAAmB,OACvB,EAAA;AACI,MAAA,IAAA,CAAK,OAAU,GAAA,OAAA,CAAA;AACf,MAAA,gBAAA,CAAiB,IAAM,EAAA,SAAA,CAAS,cAAgB,EAAA,EAAE,CAAA,CAAA;AAAA,KAGtD,MAAA;AACI,MAAA,MAAM,WAAW,EAAE,GAAG,SAAS,CAAA,cAAA,EAAgB,GAAG,OAAQ,EAAA,CAAA;AAE1D,MAAiB,gBAAA,CAAA,IAAA,EAAM,QAAU,EAAA,EAAE,CAAA,CAAA;AAAA,KACvC;AAAA,GACJ;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAiCA,IAAI,KACJ,GAAA;AACI,IAAA,OAAO,IAAK,CAAA,MAAA,CAAA;AAAA,GAChB;AAAA,EAEA,IAAI,MAAM,KACV,EAAA;AACI,IAAK,IAAA,CAAA,MAAA,GAAS,KAAK,GAAI,CAAA,IAAA,CAAK,IAAI,KAAO,EAAA,CAAC,GAAG,CAAC,CAAA,CAAA;AAE5C,IAAA,IAAA,CAAK,YAAa,EAAA,CAAA;AAAA,GACtB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAmCA,IAAI,IACJ,GAAA;AACI,IAAO,OAAA,OAAA,CAAQ,KAAK,KAAK,CAAA,CAAA;AAAA,GAC7B;AAAA,EAEA,IAAI,KAAK,KACT,EAAA;AACI,IAAI,IAAA,OAAO,UAAU,QACrB,EAAA;AACI,MAAA,IAAA,CAAK,KAAQ,GAAA,KAAA,CAAA;AAAA,KAGjB,MAAA;AACI,MAAA,IAAA,CAAK,QAAQ,KAAM,CAAA,MAAA,CAAO,SAAS,KAAS,IAAA,QAAQ,EAAE,WAAY,EAAA,CAAA;AAAA,KACtE;AAEA,IAAA,IAAA,CAAK,YAAa,EAAA,CAAA;AAAA,GACtB;AAAA,EAEQ,YACR,GAAA;AAEI,IAAA,IAAA,CAAK,QAAQ,IAAK,CAAA,KAAA,IAAA,CAAW,IAAK,CAAA,MAAA,GAAS,MAAO,CAAM,KAAA,EAAA,CAAA,CAAA;AAAA,GAC5D;AACJ,CAAA,CAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAhQa,SAAA,CAuBK,cAA2C,GAAA;AAAA,EACrD,OAAS,EAAA,CAAA;AAAA,EACT,OAAS,EAAA,CAAA;AAAA,EACT,CAAG,EAAA,CAAA;AAAA,EACH,CAAG,EAAA,CAAA;AAAA,EACH,MAAQ,EAAA,CAAA;AAAA,EACR,MAAQ,EAAA,CAAA;AAAA,EACR,QAAU,EAAA,CAAA;AAAA,EACV,IAAM,EAAA,QAAA;AAAA,EACN,KAAO,EAAA,CAAA;AACX,CAAA,CAAA;AAjCG,IAAM,QAAN,GAAA;;;;"}