@eva/plugin-renderer-mask 2.0.1-beta.3 → 2.0.1-beta.30

package/dist/EVA.plugin.renderer.mask.js

@@ -243,6 +243,7 @@ var _EVA_IIFE_mask = function (exports, eva_js, pluginRenderer, rendererAdapter)
       this.setSprite(component, sprite);
     }
     setSprite(component, sprite) {
+      var _a, _b;
       return __awaiter(this, void 0, void 0, function* () {
         let res;
         try {
@@ -254,10 +255,14 @@ var _EVA_IIFE_mask = function (exports, eva_js, pluginRenderer, rendererAdapter)
         }
         if (component.type === MASK_TYPE.Sprite) {
           const img = component.resource + resourceKeySplit + component.spriteName;
-          const texture = res.instance[img];
-          sprite.image = texture;
+          const texture = (_a = res === null || res === void 0 ? void 0 : res.instance) === null || _a === void 0 ? void 0 : _a[img];
+          if (texture) {
+            sprite.image = texture;
+          }
         } else {
-          sprite.image = res.data.image;
+          if ((_b = res === null || res === void 0 ? void 0 : res.data) === null || _b === void 0 ? void 0 : _b.image) {
+            sprite.image = res.data.image;
+          }
         }
         sprite.sprite.width = component.style.width;
         sprite.sprite.height = component.style.height;

package/dist/EVA.plugin.renderer.mask.min.js

@@ -1 +1 @@
-function _extends(){return _extends=Object.assign?Object.assign.bind():function(e){for(var t=1;t<arguments.length;t++){var r=arguments[t];for(var s in r)({}).hasOwnProperty.call(r,s)&&(e[s]=r[s])}return e},_extends.apply(null,arguments)}globalThis.EVA=globalThis.EVA||{},globalThis.EVA.plugin=globalThis.EVA.plugin||{},globalThis.EVA.plugin.renderer=globalThis.EVA.plugin.renderer||{};var _EVA_IIFE_mask=function(e,t,r,s){"use strict";function i(e,t,r,s){var i,n=arguments.length,o=n<3?t:null===s?s=Object.getOwnPropertyDescriptor(t,r):s;if("object"==typeof Reflect&&"function"==typeof Reflect.decorate)o=Reflect.decorate(e,t,r,s);else for(var c=e.length-1;c>=0;c--)(i=e[c])&&(o=(n<3?i(o):n>3?i(t,r,o):i(t,r))||o);return n>3&&o&&Object.defineProperty(t,r,o),o}function n(e,t,r,s){return new(r||(r=Promise))((function(i,n){function o(e){try{a(s.next(e))}catch(e){n(e)}}function c(e){try{a(s.throw(e))}catch(e){n(e)}}function a(e){var t;e.done?i(e.value):(t=e.value,t instanceof r?t:new r((function(e){e(t)}))).then(o,c)}a((s=s.apply(e,t||[])).next())}))}function o(e){return function(t,r){var s=function(e,t){return e.constructor.IDEProps||(e.constructor.IDEProps={}),e.constructor.IDEProps[t]||(e.constructor.IDEProps[t]={}),e.constructor.IDEProps[t]}(t,r);s.key=r,s.type=e}}e.MASK_TYPE=void 0,function(e){e.Circle="Circle",e.Ellipse="Ellipse",e.Rect="Rect",e.RoundedRect="RoundedRect",e.Polygon="Polygon",e.Img="Img",e.Sprite="Sprite"}(e.MASK_TYPE||(e.MASK_TYPE={}));class c extends t.Component{constructor(){super(...arguments),this.style={},this.resource="",this.spriteName=""}init(e){_extends(this,e)}}c.componentName="Mask",i([o("string")],c.prototype,"resource",void 0),i([o("string")],c.prototype,"spriteName",void 0);const a={Circle:["x","y","radius"],Ellipse:["x","y","width","height"],Rect:["x","y","width","height"],RoundedRect:["x","y","width","height","radius"],Polygon:["paths"]},p={Circle:"circle",Ellipse:"ellipse",Rect:"rect",RoundedRect:"roundRect",Polygon:"poly"};var h;!function(e){e.Circle="Circle",e.Ellipse="Ellipse",e.Rect="Rect",e.RoundedRect="RoundedRect",e.Polygon="Polygon",e.Img="Img",e.Sprite="Sprite"}(h||(h={}));let l=class extends r.Renderer{constructor(){super(...arguments),this.name="Mask",this.changedCache={},this.maskSpriteCache={}}init(){this.renderSystem=this.game.getSystem(r.RendererSystem),this.renderSystem.rendererManager.register(this)}rendererUpdate(){this.changedCache={}}componentChanged(e){if("Mask"===e.component.name)switch(e.type){case t.OBSERVER_TYPE.ADD:this.add(e);break;case t.OBSERVER_TYPE.REMOVE:this.remove(e);break;case t.OBSERVER_TYPE.CHANGE:this.change(e)}}add(e){const t=e.component;if(!(t.type in h))throw new Error("no have Mask type: "+t.type);if(!t.style)throw new Error("no have Mask style: "+t.type);let r;switch(t.type){case h.Circle:case h.Ellipse:case h.Rect:case h.RoundedRect:case h.Polygon:r=this.createGraphics(t);break;case h.Img:case h.Sprite:r=this.createSprite(t)}if(!r)throw new Error("no have mask instance, check your mask params: "+t.type);const s=this.containerManager.getContainer(e.gameObject.id);s.mask=r,s.addChild(r)}remove(e){const t=this.containerManager.getContainer(e.gameObject.id);t.removeChild(t.mask),t.mask.destroy({children:!0}),t.mask=null,delete this.maskSpriteCache[e.gameObject.id]}change(e){if(this.changedCache[e.gameObject.id])return;const t=e.component;"type"===e.prop.prop[0]?(this.changedCache[e.gameObject.id]=!0,[h.Sprite,h.Img].indexOf(t.type)>-1||t._lastType!==t.type?(this.remove(e),this.add(e),t._lastType=t.type):this.redrawGraphics(e)):"style"===e.prop.prop[0]?[h.Sprite,h.Img].indexOf(t.type)>-1?this.changeSpriteStyle(t):this.redrawGraphics(e):("resource"===e.prop.prop[0]||"spriteName"===e.prop.prop[0])&&(this.changedCache[e.gameObject.id]=!0,this.changeSprite(t))}createGraphics(e){const t=new s.Graphics;return this.draw(t,e),t}redrawGraphics(e){const t=this.containerManager.getContainer(e.gameObject.id).mask;t.clear(),this.draw(t,e.component)}draw(e,t){const r=[];for(const e of a[t.type])r.push(t.style[e]);e[p[t.type]](...r),e.fill(0)}createSprite(e){const t=new s.Sprite(null);return this.maskSpriteCache[e.gameObject.id]=t,this.setSprite(e,t),t.sprite}changeSpriteStyle(e){const t=this.maskSpriteCache[e.gameObject.id];t.sprite.width=e.style.width,t.sprite.height=e.style.height,t.sprite.position.x=e.style.x,t.sprite.position.y=e.style.y}changeSprite(e){const t=this.maskSpriteCache[e.gameObject.id];this.setSprite(e,t)}setSprite(e,r){return n(this,void 0,void 0,(function*(){let s;try{const r=this.increaseAsyncId(e.gameObject.id);if(s=yield t.resource.getResource(e.resource),!this.validateAsyncId(e.gameObject.id,r))return}catch(e){throw new Error("mask resource load error")}if(e.type===h.Sprite){const t=e.resource+"_s|r|c_"+e.spriteName,i=s.instance[t];r.image=i}else r.image=s.data.image;r.sprite.width=e.style.width,r.sprite.height=e.style.height,r.sprite.position.x=e.style.x,r.sprite.position.y=e.style.y}))}};l.systemName="Mask",l=i([t.decorators.componentObserver({Mask:["type",{prop:["style"],deep:!0},"resource","spriteName"]})],l);var d=l;return e.Mask=c,e.MaskSystem=d,Object.defineProperty(e,"__esModule",{value:!0}),e}({},EVA,EVA.plugin.renderer,EVA.rendererAdapter);globalThis.EVA.plugin.renderer.mask=globalThis.EVA.plugin.renderer.mask||_EVA_IIFE_mask;
+function _extends(){return _extends=Object.assign?Object.assign.bind():function(e){for(var t=1;t<arguments.length;t++){var r=arguments[t];for(var i in r)({}).hasOwnProperty.call(r,i)&&(e[i]=r[i])}return e},_extends.apply(null,arguments)}globalThis.EVA=globalThis.EVA||{},globalThis.EVA.plugin=globalThis.EVA.plugin||{},globalThis.EVA.plugin.renderer=globalThis.EVA.plugin.renderer||{};var _EVA_IIFE_mask=function(e,t,r,i){"use strict";function s(e,t,r,i){var s,n=arguments.length,o=n<3?t:null===i?i=Object.getOwnPropertyDescriptor(t,r):i;if("object"==typeof Reflect&&"function"==typeof Reflect.decorate)o=Reflect.decorate(e,t,r,i);else for(var a=e.length-1;a>=0;a--)(s=e[a])&&(o=(n<3?s(o):n>3?s(t,r,o):s(t,r))||o);return n>3&&o&&Object.defineProperty(t,r,o),o}function n(e,t,r,i){return new(r||(r=Promise))((function(s,n){function o(e){try{c(i.next(e))}catch(e){n(e)}}function a(e){try{c(i.throw(e))}catch(e){n(e)}}function c(e){var t;e.done?s(e.value):(t=e.value,t instanceof r?t:new r((function(e){e(t)}))).then(o,a)}c((i=i.apply(e,t||[])).next())}))}function o(e){return function(t,r){var i=function(e,t){return e.constructor.IDEProps||(e.constructor.IDEProps={}),e.constructor.IDEProps[t]||(e.constructor.IDEProps[t]={}),e.constructor.IDEProps[t]}(t,r);i.key=r,i.type=e}}e.MASK_TYPE=void 0,function(e){e.Circle="Circle",e.Ellipse="Ellipse",e.Rect="Rect",e.RoundedRect="RoundedRect",e.Polygon="Polygon",e.Img="Img",e.Sprite="Sprite"}(e.MASK_TYPE||(e.MASK_TYPE={}));class a extends t.Component{constructor(){super(...arguments),this.style={},this.resource="",this.spriteName=""}init(e){_extends(this,e)}}a.componentName="Mask",s([o("string")],a.prototype,"resource",void 0),s([o("string")],a.prototype,"spriteName",void 0);const c={Circle:["x","y","radius"],Ellipse:["x","y","width","height"],Rect:["x","y","width","height"],RoundedRect:["x","y","width","height","radius"],Polygon:["paths"]},p={Circle:"circle",Ellipse:"ellipse",Rect:"rect",RoundedRect:"roundRect",Polygon:"poly"};var h;!function(e){e.Circle="Circle",e.Ellipse="Ellipse",e.Rect="Rect",e.RoundedRect="RoundedRect",e.Polygon="Polygon",e.Img="Img",e.Sprite="Sprite"}(h||(h={}));let l=class extends r.Renderer{constructor(){super(...arguments),this.name="Mask",this.changedCache={},this.maskSpriteCache={}}init(){this.renderSystem=this.game.getSystem(r.RendererSystem),this.renderSystem.rendererManager.register(this)}rendererUpdate(){this.changedCache={}}componentChanged(e){if("Mask"===e.component.name)switch(e.type){case t.OBSERVER_TYPE.ADD:this.add(e);break;case t.OBSERVER_TYPE.REMOVE:this.remove(e);break;case t.OBSERVER_TYPE.CHANGE:this.change(e)}}add(e){const t=e.component;if(!(t.type in h))throw new Error("no have Mask type: "+t.type);if(!t.style)throw new Error("no have Mask style: "+t.type);let r;switch(t.type){case h.Circle:case h.Ellipse:case h.Rect:case h.RoundedRect:case h.Polygon:r=this.createGraphics(t);break;case h.Img:case h.Sprite:r=this.createSprite(t)}if(!r)throw new Error("no have mask instance, check your mask params: "+t.type);const i=this.containerManager.getContainer(e.gameObject.id);i.mask=r,i.addChild(r)}remove(e){const t=this.containerManager.getContainer(e.gameObject.id);t.removeChild(t.mask),t.mask.destroy({children:!0}),t.mask=null,delete this.maskSpriteCache[e.gameObject.id]}change(e){if(this.changedCache[e.gameObject.id])return;const t=e.component;"type"===e.prop.prop[0]?(this.changedCache[e.gameObject.id]=!0,[h.Sprite,h.Img].indexOf(t.type)>-1||t._lastType!==t.type?(this.remove(e),this.add(e),t._lastType=t.type):this.redrawGraphics(e)):"style"===e.prop.prop[0]?[h.Sprite,h.Img].indexOf(t.type)>-1?this.changeSpriteStyle(t):this.redrawGraphics(e):("resource"===e.prop.prop[0]||"spriteName"===e.prop.prop[0])&&(this.changedCache[e.gameObject.id]=!0,this.changeSprite(t))}createGraphics(e){const t=new i.Graphics;return this.draw(t,e),t}redrawGraphics(e){const t=this.containerManager.getContainer(e.gameObject.id).mask;t.clear(),this.draw(t,e.component)}draw(e,t){const r=[];for(const e of c[t.type])r.push(t.style[e]);e[p[t.type]](...r),e.fill(0)}createSprite(e){const t=new i.Sprite(null);return this.maskSpriteCache[e.gameObject.id]=t,this.setSprite(e,t),t.sprite}changeSpriteStyle(e){const t=this.maskSpriteCache[e.gameObject.id];t.sprite.width=e.style.width,t.sprite.height=e.style.height,t.sprite.position.x=e.style.x,t.sprite.position.y=e.style.y}changeSprite(e){const t=this.maskSpriteCache[e.gameObject.id];this.setSprite(e,t)}setSprite(e,r){var i,s;return n(this,void 0,void 0,(function*(){let n;try{const r=this.increaseAsyncId(e.gameObject.id);if(n=yield t.resource.getResource(e.resource),!this.validateAsyncId(e.gameObject.id,r))return}catch(e){throw new Error("mask resource load error")}if(e.type===h.Sprite){const t=e.resource+"_s|r|c_"+e.spriteName,s=null===(i=null==n?void 0:n.instance)||void 0===i?void 0:i[t];s&&(r.image=s)}else(null===(s=null==n?void 0:n.data)||void 0===s?void 0:s.image)&&(r.image=n.data.image);r.sprite.width=e.style.width,r.sprite.height=e.style.height,r.sprite.position.x=e.style.x,r.sprite.position.y=e.style.y}))}};l.systemName="Mask",l=s([t.decorators.componentObserver({Mask:["type",{prop:["style"],deep:!0},"resource","spriteName"]})],l);var d=l;return e.Mask=a,e.MaskSystem=d,Object.defineProperty(e,"__esModule",{value:!0}),e}({},EVA,EVA.plugin.renderer,EVA.rendererAdapter);globalThis.EVA.plugin.renderer.mask=globalThis.EVA.plugin.renderer.mask||_EVA_IIFE_mask;

package/dist/plugin-renderer-mask.cjs.js

@@ -48,17 +48,77 @@ exports.MASK_TYPE = void 0;
     MASK_TYPE["Img"] = "Img";
     MASK_TYPE["Sprite"] = "Sprite";
 })(exports.MASK_TYPE || (exports.MASK_TYPE = {}));
+/**
+ * 遮罩组件
+ *
+ * Mask 组件用于裁剪游戏对象的显示区域，只显示遮罩形状内的内容。
+ * 支持多种遮罩形状（矩形、圆形、多边形、图片、精灵等），
+ * 适用于头像裁剪、窗口遮罩、特殊形状显示等场景。
+ *
+ * 遮罩类型：
+ * - Circle - 圆形遮罩
+ * - Ellipse - 椭圆形遮罩
+ * - Rect - 矩形遮罩
+ * - RoundedRect - 圆角矩形遮罩
+ * - Polygon - 多边形遮罩
+ * - Img - 图片遮罩（基于图片 alpha 通道）
+ * - Sprite - 精灵遮罩
+ *
+ * @example
+ * ```typescript
+ * // 圆形头像遮罩
+ * const avatar = new GameObject('avatar');
+ * avatar.addComponent(new Img({ resource: 'userAvatar' }));
+ * avatar.addComponent(new Mask({
+ *   type: MASK_TYPE.Circle,
+ *   style: {
+ *     x: 50, // 圆心 x
+ *     y: 50, // 圆心 y
+ *     radius: 50 // 半径
+ *   }
+ * }));
+ *
+ * // 矩形遮罩
+ * avatar.addComponent(new Mask({
+ *   type: MASK_TYPE.Rect,
+ *   style: {
+ *     x: 0, y: 0,
+ *     width: 100,
+ *     height: 100
+ *   }
+ * }));
+ *
+ * // 使用图片作为遮罩
+ * avatar.addComponent(new Mask({
+ *   type: MASK_TYPE.Img,
+ *   resource: 'maskImage' // alpha 通道作为遮罩
+ * }));
+ * ```
+ */
 class Mask$2 extends eva_js.Component {
     constructor() {
         super(...arguments);
+        /** 遮罩样式配置 */
+        // @decorators.IDEProp 复杂编辑后续添加
         this.style = {};
+        /** 遮罩图片资源名称（用于 Img 类型） */
         this.resource = '';
+        /** 遮罩精灵名称（用于 Sprite 类型） */
         this.spriteName = '';
     }
+    /**
+     * 初始化组件
+     * @param obj - 初始化参数
+     * @param obj.type - 遮罩类型
+     * @param obj.style - 遮罩样式
+     * @param obj.resource - 遮罩资源（可选）
+     * @param obj.spriteName - 精灵名称（可选）
+     */
     init(obj) {
         Object.assign(this, obj);
     }
 }
+/** 组件名称 */
 Mask$2.componentName = 'Mask';
 __decorate([
     inspectorDecorator.type('string')
@@ -67,7 +127,7 @@ __decorate([
     inspectorDecorator.type('string')
 ], Mask$2.prototype, "spriteName", void 0);
 
-const resourceKeySplit = '_s|r|c_';
+const resourceKeySplit = '_s|r|c_'; // Notice: This key be created by sprite system.
 const propertyForGraphics = {
     Circle: ['x', 'y', 'radius'],
     Ellipse: ['x', 'y', 'width', 'height'],
@@ -215,6 +275,7 @@ let Mask = class Mask extends pluginRenderer.Renderer {
         for (const key of propertyForGraphics[component.type]) {
             params.push(component.style[key]);
         }
+        // @ts-ignore
         graphics[functionForGraphics[component.type]](...params);
         graphics.fill(0x000000);
     }
@@ -236,6 +297,7 @@ let Mask = class Mask extends pluginRenderer.Renderer {
         this.setSprite(component, sprite);
     }
     setSprite(component, sprite) {
+        var _a, _b;
         return __awaiter(this, void 0, void 0, function* () {
             let res;
             try {
@@ -249,11 +311,15 @@ let Mask = class Mask extends pluginRenderer.Renderer {
             }
             if (component.type === MASK_TYPE.Sprite) {
                 const img = component.resource + resourceKeySplit + component.spriteName;
-                const texture = res.instance[img];
-                sprite.image = texture;
+                const texture = (_a = res === null || res === void 0 ? void 0 : res.instance) === null || _a === void 0 ? void 0 : _a[img];
+                if (texture) {
+                    sprite.image = texture;
+                }
             }
             else {
-                sprite.image = res.data.image;
+                if ((_b = res === null || res === void 0 ? void 0 : res.data) === null || _b === void 0 ? void 0 : _b.image) {
+                    sprite.image = res.data.image;
+                }
             }
             sprite.sprite.width = component.style.width;
             sprite.sprite.height = component.style.height;

package/dist/plugin-renderer-mask.cjs.prod.js

@@ -13,4 +13,4 @@ MERCHANTABLITY OR NON-INFRINGEMENT.
 See the Apache Version 2.0 License for specific language governing permissions
 and limitations under the License.
 ***************************************************************************** */
-function s(e,t,r,i){var s,a=arguments.length,c=a<3?t:null===i?i=Object.getOwnPropertyDescriptor(t,r):i;if("object"==typeof Reflect&&"function"==typeof Reflect.decorate)c=Reflect.decorate(e,t,r,i);else for(var n=e.length-1;n>=0;n--)(s=e[n])&&(c=(a<3?s(c):a>3?s(t,r,c):s(t,r))||c);return a>3&&c&&Object.defineProperty(t,r,c),c}exports.MASK_TYPE=void 0,function(e){e.Circle="Circle",e.Ellipse="Ellipse",e.Rect="Rect",e.RoundedRect="RoundedRect",e.Polygon="Polygon",e.Img="Img",e.Sprite="Sprite"}(exports.MASK_TYPE||(exports.MASK_TYPE={}));class a extends e.Component{constructor(){super(...arguments),this.style={},this.resource="",this.spriteName=""}init(e){Object.assign(this,e)}}a.componentName="Mask",s([t.type("string")],a.prototype,"resource",void 0),s([t.type("string")],a.prototype,"spriteName",void 0);const c={Circle:["x","y","radius"],Ellipse:["x","y","width","height"],Rect:["x","y","width","height"],RoundedRect:["x","y","width","height","radius"],Polygon:["paths"]},n={Circle:"circle",Ellipse:"ellipse",Rect:"rect",RoundedRect:"roundRect",Polygon:"poly"};var o;!function(e){e.Circle="Circle",e.Ellipse="Ellipse",e.Rect="Rect",e.RoundedRect="RoundedRect",e.Polygon="Polygon",e.Img="Img",e.Sprite="Sprite"}(o||(o={}));let p=class extends r.Renderer{constructor(){super(...arguments),this.name="Mask",this.changedCache={},this.maskSpriteCache={}}init(){this.renderSystem=this.game.getSystem(r.RendererSystem),this.renderSystem.rendererManager.register(this)}rendererUpdate(){this.changedCache={}}componentChanged(t){if("Mask"===t.component.name)switch(t.type){case e.OBSERVER_TYPE.ADD:this.add(t);break;case e.OBSERVER_TYPE.REMOVE:this.remove(t);break;case e.OBSERVER_TYPE.CHANGE:this.change(t)}}add(e){const t=e.component;if(!(t.type in o))throw new Error("no have Mask type: "+t.type);if(!t.style)throw new Error("no have Mask style: "+t.type);let r;switch(t.type){case o.Circle:case o.Ellipse:case o.Rect:case o.RoundedRect:case o.Polygon:r=this.createGraphics(t);break;case o.Img:case o.Sprite:r=this.createSprite(t)}if(!r)throw new Error("no have mask instance, check your mask params: "+t.type);const i=this.containerManager.getContainer(e.gameObject.id);i.mask=r,i.addChild(r)}remove(e){const t=this.containerManager.getContainer(e.gameObject.id);t.removeChild(t.mask),t.mask.destroy({children:!0}),t.mask=null,delete this.maskSpriteCache[e.gameObject.id]}change(e){if(this.changedCache[e.gameObject.id])return;const t=e.component;"type"===e.prop.prop[0]?(this.changedCache[e.gameObject.id]=!0,[o.Sprite,o.Img].indexOf(t.type)>-1||t._lastType!==t.type?(this.remove(e),this.add(e),t._lastType=t.type):this.redrawGraphics(e)):"style"===e.prop.prop[0]?[o.Sprite,o.Img].indexOf(t.type)>-1?this.changeSpriteStyle(t):this.redrawGraphics(e):("resource"===e.prop.prop[0]||"spriteName"===e.prop.prop[0])&&(this.changedCache[e.gameObject.id]=!0,this.changeSprite(t))}createGraphics(e){const t=new i.Graphics;return this.draw(t,e),t}redrawGraphics(e){const t=this.containerManager.getContainer(e.gameObject.id).mask;t.clear(),this.draw(t,e.component)}draw(e,t){const r=[];for(const e of c[t.type])r.push(t.style[e]);e[n[t.type]](...r),e.fill(0)}createSprite(e){const t=new i.Sprite(null);return this.maskSpriteCache[e.gameObject.id]=t,this.setSprite(e,t),t.sprite}changeSpriteStyle(e){const t=this.maskSpriteCache[e.gameObject.id];t.sprite.width=e.style.width,t.sprite.height=e.style.height,t.sprite.position.x=e.style.x,t.sprite.position.y=e.style.y}changeSprite(e){const t=this.maskSpriteCache[e.gameObject.id];this.setSprite(e,t)}setSprite(t,r){return i=this,s=void 0,c=function*(){let i;try{const r=this.increaseAsyncId(t.gameObject.id);if(i=yield e.resource.getResource(t.resource),!this.validateAsyncId(t.gameObject.id,r))return}catch(e){throw new Error("mask resource load error")}if(t.type===o.Sprite){const e=t.resource+"_s|r|c_"+t.spriteName,s=i.instance[e];r.image=s}else r.image=i.data.image;r.sprite.width=t.style.width,r.sprite.height=t.style.height,r.sprite.position.x=t.style.x,r.sprite.position.y=t.style.y},new((a=void 0)||(a=Promise))((function(e,t){function r(e){try{o(c.next(e))}catch(e){t(e)}}function n(e){try{o(c.throw(e))}catch(e){t(e)}}function o(t){t.done?e(t.value):new a((function(e){e(t.value)})).then(r,n)}o((c=c.apply(i,s||[])).next())}));var i,s,a,c}};p.systemName="Mask",p=s([e.decorators.componentObserver({Mask:["type",{prop:["style"],deep:!0},"resource","spriteName"]})],p);var h=p;exports.Mask=a,exports.MaskSystem=h;
+function s(e,t,r,i){var s,a=arguments.length,n=a<3?t:null===i?i=Object.getOwnPropertyDescriptor(t,r):i;if("object"==typeof Reflect&&"function"==typeof Reflect.decorate)n=Reflect.decorate(e,t,r,i);else for(var c=e.length-1;c>=0;c--)(s=e[c])&&(n=(a<3?s(n):a>3?s(t,r,n):s(t,r))||n);return a>3&&n&&Object.defineProperty(t,r,n),n}exports.MASK_TYPE=void 0,function(e){e.Circle="Circle",e.Ellipse="Ellipse",e.Rect="Rect",e.RoundedRect="RoundedRect",e.Polygon="Polygon",e.Img="Img",e.Sprite="Sprite"}(exports.MASK_TYPE||(exports.MASK_TYPE={}));class a extends e.Component{constructor(){super(...arguments),this.style={},this.resource="",this.spriteName=""}init(e){Object.assign(this,e)}}a.componentName="Mask",s([t.type("string")],a.prototype,"resource",void 0),s([t.type("string")],a.prototype,"spriteName",void 0);const n={Circle:["x","y","radius"],Ellipse:["x","y","width","height"],Rect:["x","y","width","height"],RoundedRect:["x","y","width","height","radius"],Polygon:["paths"]},c={Circle:"circle",Ellipse:"ellipse",Rect:"rect",RoundedRect:"roundRect",Polygon:"poly"};var o;!function(e){e.Circle="Circle",e.Ellipse="Ellipse",e.Rect="Rect",e.RoundedRect="RoundedRect",e.Polygon="Polygon",e.Img="Img",e.Sprite="Sprite"}(o||(o={}));let p=class extends r.Renderer{constructor(){super(...arguments),this.name="Mask",this.changedCache={},this.maskSpriteCache={}}init(){this.renderSystem=this.game.getSystem(r.RendererSystem),this.renderSystem.rendererManager.register(this)}rendererUpdate(){this.changedCache={}}componentChanged(t){if("Mask"===t.component.name)switch(t.type){case e.OBSERVER_TYPE.ADD:this.add(t);break;case e.OBSERVER_TYPE.REMOVE:this.remove(t);break;case e.OBSERVER_TYPE.CHANGE:this.change(t)}}add(e){const t=e.component;if(!(t.type in o))throw new Error("no have Mask type: "+t.type);if(!t.style)throw new Error("no have Mask style: "+t.type);let r;switch(t.type){case o.Circle:case o.Ellipse:case o.Rect:case o.RoundedRect:case o.Polygon:r=this.createGraphics(t);break;case o.Img:case o.Sprite:r=this.createSprite(t)}if(!r)throw new Error("no have mask instance, check your mask params: "+t.type);const i=this.containerManager.getContainer(e.gameObject.id);i.mask=r,i.addChild(r)}remove(e){const t=this.containerManager.getContainer(e.gameObject.id);t.removeChild(t.mask),t.mask.destroy({children:!0}),t.mask=null,delete this.maskSpriteCache[e.gameObject.id]}change(e){if(this.changedCache[e.gameObject.id])return;const t=e.component;"type"===e.prop.prop[0]?(this.changedCache[e.gameObject.id]=!0,[o.Sprite,o.Img].indexOf(t.type)>-1||t._lastType!==t.type?(this.remove(e),this.add(e),t._lastType=t.type):this.redrawGraphics(e)):"style"===e.prop.prop[0]?[o.Sprite,o.Img].indexOf(t.type)>-1?this.changeSpriteStyle(t):this.redrawGraphics(e):("resource"===e.prop.prop[0]||"spriteName"===e.prop.prop[0])&&(this.changedCache[e.gameObject.id]=!0,this.changeSprite(t))}createGraphics(e){const t=new i.Graphics;return this.draw(t,e),t}redrawGraphics(e){const t=this.containerManager.getContainer(e.gameObject.id).mask;t.clear(),this.draw(t,e.component)}draw(e,t){const r=[];for(const e of n[t.type])r.push(t.style[e]);e[c[t.type]](...r),e.fill(0)}createSprite(e){const t=new i.Sprite(null);return this.maskSpriteCache[e.gameObject.id]=t,this.setSprite(e,t),t.sprite}changeSpriteStyle(e){const t=this.maskSpriteCache[e.gameObject.id];t.sprite.width=e.style.width,t.sprite.height=e.style.height,t.sprite.position.x=e.style.x,t.sprite.position.y=e.style.y}changeSprite(e){const t=this.maskSpriteCache[e.gameObject.id];this.setSprite(e,t)}setSprite(t,r){var i,s,a,n,c,p;return a=this,n=void 0,p=function*(){let a;try{const r=this.increaseAsyncId(t.gameObject.id);if(a=yield e.resource.getResource(t.resource),!this.validateAsyncId(t.gameObject.id,r))return}catch(e){throw new Error("mask resource load error")}if(t.type===o.Sprite){const e=t.resource+"_s|r|c_"+t.spriteName,s=null===(i=null==a?void 0:a.instance)||void 0===i?void 0:i[e];s&&(r.image=s)}else(null===(s=null==a?void 0:a.data)||void 0===s?void 0:s.image)&&(r.image=a.data.image);r.sprite.width=t.style.width,r.sprite.height=t.style.height,r.sprite.position.x=t.style.x,r.sprite.position.y=t.style.y},new((c=void 0)||(c=Promise))((function(e,t){function r(e){try{s(p.next(e))}catch(e){t(e)}}function i(e){try{s(p.throw(e))}catch(e){t(e)}}function s(t){t.done?e(t.value):new c((function(e){e(t.value)})).then(r,i)}s((p=p.apply(a,n||[])).next())}))}};p.systemName="Mask",p=s([e.decorators.componentObserver({Mask:["type",{prop:["style"],deep:!0},"resource","spriteName"]})],p);var h=p;exports.Mask=a,exports.MaskSystem=h;

package/dist/plugin-renderer-mask.d.ts

@@ -8,13 +8,74 @@ import { RendererSystem } from '@eva/plugin-renderer';
 import { Sprite } from '@eva/renderer-adapter';
 import type { Sprite as Sprite_2 } from 'pixi.js';
 
+/**
+ * 遮罩组件
+ *
+ * Mask 组件用于裁剪游戏对象的显示区域，只显示遮罩形状内的内容。
+ * 支持多种遮罩形状（矩形、圆形、多边形、图片、精灵等），
+ * 适用于头像裁剪、窗口遮罩、特殊形状显示等场景。
+ *
+ * 遮罩类型：
+ * - Circle - 圆形遮罩
+ * - Ellipse - 椭圆形遮罩
+ * - Rect - 矩形遮罩
+ * - RoundedRect - 圆角矩形遮罩
+ * - Polygon - 多边形遮罩
+ * - Img - 图片遮罩（基于图片 alpha 通道）
+ * - Sprite - 精灵遮罩
+ *
+ * @example
+ * ```typescript
+ * // 圆形头像遮罩
+ * const avatar = new GameObject('avatar');
+ * avatar.addComponent(new Img({ resource: 'userAvatar' }));
+ * avatar.addComponent(new Mask({
+ *   type: MASK_TYPE.Circle,
+ *   style: {
+ *     x: 50, // 圆心 x
+ *     y: 50, // 圆心 y
+ *     radius: 50 // 半径
+ *   }
+ * }));
+ *
+ * // 矩形遮罩
+ * avatar.addComponent(new Mask({
+ *   type: MASK_TYPE.Rect,
+ *   style: {
+ *     x: 0, y: 0,
+ *     width: 100,
+ *     height: 100
+ *   }
+ * }));
+ *
+ * // 使用图片作为遮罩
+ * avatar.addComponent(new Mask({
+ *   type: MASK_TYPE.Img,
+ *   resource: 'maskImage' // alpha 通道作为遮罩
+ * }));
+ * ```
+ */
 export declare class Mask extends Component<MaskParams> {
+    /** 组件名称 */
     static componentName: string;
+    /** 上一次的遮罩类型 */
     _lastType: MaskParams['type'];
+    /** 遮罩类型 */
     type: MaskParams['type'];
+    /** 遮罩样式配置 */
     style?: MaskParams['style'];
+    /** 遮罩图片资源名称（用于 Img 类型） */
     resource?: string;
+    /** 遮罩精灵名称（用于 Sprite 类型） */
     spriteName?: string;
+    /**
+     * 初始化组件
+     * @param obj - 初始化参数
+     * @param obj.type - 遮罩类型
+     * @param obj.style - 遮罩样式
+     * @param obj.resource - 遮罩资源（可选）
+     * @param obj.spriteName - 精灵名称（可选）
+     */
     init(obj?: MaskParams): void;
 }
 

package/dist/plugin-renderer-mask.esm.js

@@ -44,17 +44,77 @@ var MASK_TYPE$1;
     MASK_TYPE["Img"] = "Img";
     MASK_TYPE["Sprite"] = "Sprite";
 })(MASK_TYPE$1 || (MASK_TYPE$1 = {}));
+/**
+ * 遮罩组件
+ *
+ * Mask 组件用于裁剪游戏对象的显示区域，只显示遮罩形状内的内容。
+ * 支持多种遮罩形状（矩形、圆形、多边形、图片、精灵等），
+ * 适用于头像裁剪、窗口遮罩、特殊形状显示等场景。
+ *
+ * 遮罩类型：
+ * - Circle - 圆形遮罩
+ * - Ellipse - 椭圆形遮罩
+ * - Rect - 矩形遮罩
+ * - RoundedRect - 圆角矩形遮罩
+ * - Polygon - 多边形遮罩
+ * - Img - 图片遮罩（基于图片 alpha 通道）
+ * - Sprite - 精灵遮罩
+ *
+ * @example
+ * ```typescript
+ * // 圆形头像遮罩
+ * const avatar = new GameObject('avatar');
+ * avatar.addComponent(new Img({ resource: 'userAvatar' }));
+ * avatar.addComponent(new Mask({
+ *   type: MASK_TYPE.Circle,
+ *   style: {
+ *     x: 50, // 圆心 x
+ *     y: 50, // 圆心 y
+ *     radius: 50 // 半径
+ *   }
+ * }));
+ *
+ * // 矩形遮罩
+ * avatar.addComponent(new Mask({
+ *   type: MASK_TYPE.Rect,
+ *   style: {
+ *     x: 0, y: 0,
+ *     width: 100,
+ *     height: 100
+ *   }
+ * }));
+ *
+ * // 使用图片作为遮罩
+ * avatar.addComponent(new Mask({
+ *   type: MASK_TYPE.Img,
+ *   resource: 'maskImage' // alpha 通道作为遮罩
+ * }));
+ * ```
+ */
 class Mask$2 extends Component {
     constructor() {
         super(...arguments);
+        /** 遮罩样式配置 */
+        // @decorators.IDEProp 复杂编辑后续添加
         this.style = {};
+        /** 遮罩图片资源名称（用于 Img 类型） */
         this.resource = '';
+        /** 遮罩精灵名称（用于 Sprite 类型） */
         this.spriteName = '';
     }
+    /**
+     * 初始化组件
+     * @param obj - 初始化参数
+     * @param obj.type - 遮罩类型
+     * @param obj.style - 遮罩样式
+     * @param obj.resource - 遮罩资源（可选）
+     * @param obj.spriteName - 精灵名称（可选）
+     */
     init(obj) {
         Object.assign(this, obj);
     }
 }
+/** 组件名称 */
 Mask$2.componentName = 'Mask';
 __decorate([
     type('string')
@@ -63,7 +123,7 @@ __decorate([
     type('string')
 ], Mask$2.prototype, "spriteName", void 0);
 
-const resourceKeySplit = '_s|r|c_';
+const resourceKeySplit = '_s|r|c_'; // Notice: This key be created by sprite system.
 const propertyForGraphics = {
     Circle: ['x', 'y', 'radius'],
     Ellipse: ['x', 'y', 'width', 'height'],
@@ -211,6 +271,7 @@ let Mask = class Mask extends Renderer {
         for (const key of propertyForGraphics[component.type]) {
             params.push(component.style[key]);
         }
+        // @ts-ignore
         graphics[functionForGraphics[component.type]](...params);
         graphics.fill(0x000000);
     }
@@ -232,6 +293,7 @@ let Mask = class Mask extends Renderer {
         this.setSprite(component, sprite);
     }
     setSprite(component, sprite) {
+        var _a, _b;
         return __awaiter(this, void 0, void 0, function* () {
             let res;
             try {
@@ -245,11 +307,15 @@ let Mask = class Mask extends Renderer {
             }
             if (component.type === MASK_TYPE.Sprite) {
                 const img = component.resource + resourceKeySplit + component.spriteName;
-                const texture = res.instance[img];
-                sprite.image = texture;
+                const texture = (_a = res === null || res === void 0 ? void 0 : res.instance) === null || _a === void 0 ? void 0 : _a[img];
+                if (texture) {
+                    sprite.image = texture;
+                }
             }
             else {
-                sprite.image = res.data.image;
+                if ((_b = res === null || res === void 0 ? void 0 : res.data) === null || _b === void 0 ? void 0 : _b.image) {
+                    sprite.image = res.data.image;
+                }
             }
             sprite.sprite.width = component.style.width;
             sprite.sprite.height = component.style.height;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eva/plugin-renderer-mask",
-  "version": "2.0.1-beta.3",
+  "version": "2.0.1-beta.30",
   "description": "@eva/plugin-renderer-mask",
   "main": "index.js",
   "module": "dist/plugin-renderer-mask.esm.js",
@@ -19,9 +19,9 @@
   "homepage": "https://eva.js.org",
   "dependencies": {
     "@eva/inspector-decorator": "^0.0.5",
-    "@eva/plugin-renderer": "2.0.1-beta.3",
-    "@eva/renderer-adapter": "2.0.1-beta.3",
-    "@eva/eva.js": "2.0.1-beta.3",
+    "@eva/plugin-renderer": "2.0.1-beta.30",
+    "@eva/renderer-adapter": "2.0.1-beta.30",
+    "@eva/eva.js": "2.0.1-beta.30",
     "pixi.js": "^8.8.1"
   }
 }