简介本资源是一个基于Laya引擎实现的Unity粒子系统Web预览Demo面向前端开发者、游戏开发初学者及3D网页交互实践者解决Unity导出粒子在浏览器中动态加载与实时预览的技术难点。项目支持通过弹窗选择本地.lh粒子文件兼容最多两层嵌套无需重启即可热切换不同粒子效果提供播放/暂停控制、键盘鼠标自由视角漫游并实现3D场景与HTML元素混合渲染适用于LayaIDE环境下的快速验证与教学演示。压缩包共302个文件含6个核心.lh粒子资源、67个JS逻辑脚本、51个PNG贴图、13个JSON配置及多个.lmat材质文件辅以HTML入口与README说明整体体积23.43MB结构完整、即开即用。目前已有743人学习下载读者可直接运行获得可交互的粒子预览环境掌握DOM操作触发文件读取、Laya 3D场景生命周期管理及跨引擎资源适配的关键实践路径。1. 一个被低估的粒子调试场景Unity导出的粒子效果在Laya里不改一行C#就能本地预览你有没有遇到过这种场景美术在Unity里调好了一套炫酷的粒子特效导出为.prefab或.assetbundle后扔给前端结果H5端一跑——粒子不动、贴图错位、缩放失真甚至直接白屏。排查时发现问题根本不在Laya渲染逻辑而卡在「资源加载路径没对上」、「Unity导出配置漏了Alpha通道」、「粒子系统用到了Laya尚未兼容的Emitter模式」这些细节上。这个项目就是为这类真实翻车现场而生的它不依赖服务器、不走构建流程、不碰Unity Editor插件只用一个轻量HTML页面 原生DOM文件选择器就能把本地导出的Unity粒子资源.json.png组合拖进来实时预览完整生命周期。适合Unity策划、TA、前端联调工程师——尤其当你手头只有导出物、没有源工程、又急需验证粒子行为是否符合预期时它就是你的后悔药。2. 架构与技术选型为什么是Laya DOM File API而不是WebGL手动封装2.1 核心定位不是粒子引擎重写而是Unity-Laya资产链路的“最后一公里”验证工具这个项目本质是一个离线资产桥接器而非通用粒子编辑器。它不实现ParticleSystem底层模拟那是Laya引擎的事也不解析Unity的.meta或.asset二进制格式太重且易过时。它专注解决三个具体问题路径映射Unity导出的JSON里写的贴图路径是Assets/Textures/spark.png但浏览器里只能读./textures/spark.png需要运行时重写资源注入把用户选中的PNG文件转成ImageBitmap或Texture2D对象塞进Laya的Texture管理器生命周期控制提供Play/Pause/Reset按钮对应调用Particle2D.play()、stop()、reset()避免粒子自动销毁后无法二次触发。提示它不处理Shader替换、GPU Instancing优化、多Pass渲染等高级特性——那些属于生产环境适配范畴本项目只保证「能动、能看、能调参」。2.2 技术栈拆解LayaAir 3.x 原生File API JSON Schema校验模块技术选型为什么不用别的渲染引擎LayaAir 3.0.4WebGL2Unity导出的粒子JSON结构与LayaParticle2D高度兼容且3.x已内置Particle2D.fromJSON()方法若用Pixi.js需自己解析JSON并映射到PIXI.ParticleContainer工作量翻倍文件操作input[typefile]FileReaderURL.createObjectURL()不用input typefile webkitdirectory目录上传兼容性差也不用showOpenFilePicker()Safari不支持原生File API覆盖所有现代浏览器且能精确控制单文件/多文件加载顺序资源校验JSON Schema精简版对Unity导出的particle.json做字段存在性检查如texturePath、emissionRate避免因导出配置错误导致静默失败不用正则硬匹配Schema可随Laya版本升级灵活调整2.3 目录结构6个文件撑起全部功能无构建、无打包、开箱即用laya-unity-particle-preview/ ├── index.html # 主页含文件选择器、Canvas容器、控制面板 ├── main.js # 入口初始化Laya、绑定DOM事件、处理文件流 ├── particle-loader.js # 核心解析JSON、加载贴图、创建Particle2D实例 ├── utils/dom-helper.js # DOM工具动态创建按钮、状态提示、错误弹窗 ├── assets/ # 示例资源非必需unity-exported/particle.json spark.png └── README.md # 快速启动说明含Unity导出配置要点注意assets/目录仅作演示实际使用时用户通过文件选择器指定任意本地路径项目不依赖固定目录结构。3. 核心模块拆解从文件选择到粒子播放的完整链路3.1 文件选择与解析如何让input typefile精准识别Unity导出包Unity导出粒子时通常生成两个文件一个描述参数的xxx.json一个存放贴图的xxx.png或xxx.atlas。本项目要求用户同时选中这两个文件而非单个文件——这是避免路径错乱的关键设计。main.js中监听change事件的代码如下// main.js document.getElementById(fileInput).addEventListener(change, async (e) { const files Array.from(e.target.files); if (files.length 2) { showErrorMessage(请同时选择 .json 和 .png 文件); return; } // 分离JSON和PNG文件 const jsonFile files.find(f f.name.endsWith(.json)); const pngFile files.find(f f.name.endsWith(.png)); if (!jsonFile || !pngFile) { showErrorMessage(未找到 .json 或 .png 文件请检查文件类型); return; } try { // 并行读取两个文件 const [jsonContent, pngBlob] await Promise.all([ readFileAsText(jsonFile), readFileAsBlob(pngFile) ]); const particleData JSON.parse(jsonContent); loadAndPlayParticle(particleData, pngBlob, jsonFile.name); } catch (err) { showErrorMessage(文件解析失败${err.message}); } }); function readFileAsText(file) { return new Promise((resolve, reject) { const reader new FileReader(); reader.onload () resolve(reader.result); reader.onerror () reject(reader.error); reader.readAsText(file); }); } function readFileAsBlob(file) { return new Promise((resolve, reject) { const reader new FileReader(); reader.onload () resolve(reader.result); reader.onerror () reject(reader.error); reader.readAsArrayBuffer(file); }); }关键点说明readFileAsText()用于JSON确保UTF-8编码正确readFileAsBlob()用于PNG保留二进制完整性Promise.all()保证JSON和PNG同时就绪再执行后续避免因异步时序导致texture未加载完就调用play()jsonFile.name传入loadAndPlayParticle()用于提取基础路径如fire.json→fire.png辅助后续路径映射。3.2 粒子加载器particle-loader.js如何把JSONPNG变成可播放的Particle2Dparticle-loader.js是整个项目最核心的模块它完成三件事校验JSON结构、创建贴图对象、实例化粒子系统。以下是关键代码段// particle-loader.js export function loadAndPlayParticle(jsonData, pngBlob, jsonFileName) { // Step 1: JSON Schema校验简化版 if (!jsonData.texturePath || typeof jsonData.emissionRate ! number) { throw new Error(JSON缺少必要字段texturePath 或 emissionRate); } // Step 2: 从jsonFileName推导贴图名如 fire.json → fire.png const baseName jsonFileName.replace(/\.json$/, ); const expectedPngName ${baseName}.png; // Step 3: 创建Laya Texture对象 const texture new Laya.Texture(); texture.bitmap new Laya.BrowserImage(); texture.bitmap.src URL.createObjectURL(new Blob([pngBlob], { type: image/png })); // Step 4: 创建Particle2D实例并注入JSON参数 const particle Laya.Particle2D.fromJSON(jsonData); particle.texture texture; // 关键必须显式赋值否则用默认白图 // Step 5: 修正JSON中硬编码的路径如 Assets/Textures/spark.png → spark.png if (jsonData.texturePath jsonData.texturePath.includes(/)) { particle.texturePath jsonData.texturePath.split(/).pop(); // 取文件名部分 } // Step 6: 添加到舞台并播放 Laya.stage.addChild(particle); particle.play(true); // true表示循环播放 return particle; }参数说明与逻辑延伸jsonData.texturePathUnity导出JSON中记录的贴图路径本项目不依赖该路径加载文件因为用户已选中PNG但会从中提取文件名用于日志和调试URL.createObjectURL()将ArrayBuffer转为浏览器可识别的URL避免跨域问题Laya.BrowserImage是Laya 3.x中处理动态图片的标准方式particle.play(true)第二个参数true表示循环false则播放一次后停止若需手动控制可改为particle.play(false)后续通过按钮调用particle.reset()重启玄学注意Laya 3.x中Particle2D.fromJSON()会忽略JSON里的texture字段必须手动particle.texture texture否则永远显示默认白点——这是官方文档未明说的坑。3.3 控制面板实现用原生DOM驱动Laya粒子生命周期控制面板包含三个按钮Play、Pause、Reset它们不操作DOM样式而是直接调用Laya粒子实例的方法。utils/dom-helper.js中代码如下// utils/dom-helper.js export function createControlPanel(particleInstance) { const panel document.createElement(div); panel.className control-panel; panel.innerHTML button idplayBtn▶ Play/button button idpauseBtn⏸ Pause/button button idresetBtn↺ Reset/button ; document.body.appendChild(panel); // 绑定事件注意必须在particleInstance存在后绑定 document.getElementById(playBtn).onclick () { if (particleInstance.isStopped()) { particleInstance.play(true); } }; document.getElementById(pauseBtn).onclick () { if (!particleInstance.isStopped()) { particleInstance.stop(); } }; document.getElementById(resetBtn).onclick () { particleInstance.reset(); particleInstance.play(true); }; }为什么不用Laya UI组件本项目定位是「调试工具」非正式产品界面原生DOM按钮响应更快无Laya UI渲染开销避免引入Laya.UI模块增加包体积当前总JS小于80KB。4. 避坑指南5个真实踩过的坑与血泪解决方案4.1 现象粒子完全不显示控制台无报错Canvas区域纯黑原因Unity导出时未勾选Export Texture选项JSON中texturePath为空但particle-loader.js未做空值防御particle.texture被设为undefinedLaya默认用黑色背景渲染。解决在loadAndPlayParticle()开头增加校验if (!pngBlob) { throw new Error(PNG文件未加载成功请检查文件选择是否正确); }4.2 现象粒子播放但颜色全白无透明度渐变原因Unity导出的PNG未启用Alpha通道如保存为RGB而非RGBA或浏览器加载时未设置premultiplyAlpha: false。解决在创建BrowserImage后强制设置texture.bitmap new Laya.BrowserImage(); texture.bitmap.src url; texture.bitmap.premultiplyAlpha false; // 关键否则Alpha被错误叠加4.3 现象粒子位置偏移始终出现在Canvas左上角而非中心原因Unity导出JSON中position字段为[0,0,0]但LayaParticle2D默认锚点在左上角未调用pivotX/pivotY居中。解决加载后自动居中particle.pivotX particle.width / 2; particle.pivotY particle.height / 2; particle.x Laya.stage.width / 2; particle.y Laya.stage.height / 2;4.4 现象多次选择不同粒子文件后内存持续增长最终卡死原因每次loadAndPlayParticle()都创建新Texture和Particle2D但旧实例未从舞台移除也未调用texture.destroy()释放GPU内存。解决维护全局实例引用销毁前清理let currentParticle null; let currentTexture null; export function loadAndPlayParticle(jsonData, pngBlob, jsonFileName) { // 销毁上一个实例 if (currentParticle) { currentParticle.removeSelf(); currentParticle.destroy(); } if (currentTexture) { currentTexture.destroy(); } // ...后续创建逻辑 currentParticle particle; currentTexture texture; }4.5 现象Safari浏览器下URL.createObjectURL()报错TypeError: Type error原因Safari对Blob构造函数的type参数校验更严格image/png可能被拒绝。解决去掉type参数让浏览器自动推断// 错误写法 new Blob([pngBlob], { type: image/png }) // 正确写法Safari兼容 new Blob([pngBlob])5. 二次开发实战如何扩展支持Atlas图集与参数实时调节5.1 支持Unity导出的.atlas图集三步改造particle-loader.jsUnity导出粒子时可选择Sprite Atlas模式生成xxx.atlas文本xxx.png大图组合。此时JSON中texturePath指向.atlas文件而非单张PNG。扩展步骤如下Step 1修改文件类型判断逻辑在main.js的change事件中增加对.atlas的支持const atlasFile files.find(f f.name.endsWith(.atlas)); const pngFile files.find(f f.name.endsWith(.png)); if (atlasFile pngFile) { // 加载atlas模式 loadAtlasParticle(atlasFile, pngFile, jsonData); } else { // 原有单图模式 }Step 2解析.atlas文本并提取子图信息.atlas是文本格式内容类似spark.png size: 1024,1024 format: RGBA8888 filter: Linear,Linear repeat: none spark rotate: false xy: 0, 0 size: 64, 64 orig: 64, 64 offset: 0, 0 index: -1需解析出spark子图的xy、size生成Texture的uv坐标。关键代码function parseAtlas(atlasText, pngBlob) { const lines atlasText.split(\n); const subImages {}; let currentName ; for (let i 0; i lines.length; i) { const line lines[i].trim(); if (line.endsWith(:)) { currentName line.replace(:, ).trim(); subImages[currentName] {}; } else if (line.startsWith(xy:)) { const [x, y] line.replace(xy:, ).split(,).map(n parseInt(n.trim())); subImages[currentName].uv [x/1024, y/1024, (x64)/1024, (y64)/1024]; // 假设size64 } } return { texture: createTextureFromBlob(pngBlob), subImages }; }Step 3为粒子指定子图UVLayaParticle2D支持subTexture需在fromJSON()后设置const atlas parseAtlas(atlasText, pngBlob); particle.texture atlas.texture; particle.subTexture new Laya.SubTexture( atlas.texture, atlas.subImages[spark].uv[0], atlas.subImages[spark].uv[1], atlas.subImages[spark].uv[2] - atlas.subImages[spark].uv[0], atlas.subImages[spark].uv[3] - atlas.subImages[spark].uv[1] );5.2 实现参数实时调节用input typerange驱动粒子属性为快速验证参数影响可在控制面板增加滑块。例如调节发射率emissionRate!-- 在control-panel中追加 -- div classparam-control labelEmission Rate: span idrateValue30/span/label input typerange idrateSlider min1 max100 value30 /div// 绑定滑块事件 document.getElementById(rateSlider).oninput (e) { const value parseInt(e.target.value); document.getElementById(rateValue).textContent value; if (currentParticle) { currentParticle.emissionRate value; } };注意LayaParticle2D的emissionRate是只读属性需通过setEmissionRate()方法修改// 正确写法 particle.setEmissionRate(value);5.3 一个实用技巧用localStorage记住最近加载的粒子配置避免每次重启都要重新选文件可将jsonFileName和lastLoadedTime存入localStorage// 加载成功后 localStorage.setItem(lastParticle, JSON.stringify({ fileName: jsonFileName, timestamp: Date.now() })); // 页面初始化时检查 const last localStorage.getItem(lastParticle); if (last) { const info JSON.parse(last); showLastLoadedTip(上次加载${info.fileName}${new Date(info.timestamp).toLocaleTimeString()}); }从那以后我每次做Unity-Laya联调都会先把这个预览页丢进测试机桌面遇到粒子异常第一反应不是翻文档而是拖两个文件进去——3秒内确认是资源问题还是引擎兼容问题。省下的时间够我多喝两杯咖啡。希望帮到你。本文还有配套的精品资源点击获取