@eva/plugin-renderer-filter 2.1.0-beta.1

package/lib/component.ts

@@ -0,0 +1,89 @@
+import { Component } from "@eva/eva.js";
+
+export type FilterType = "blur" | "colorMatrix" | "displacement" | "noise" | "alpha";
+
+export type ColorMatrixPreset =
+	| "sepia"
+	| "grayscale"
+	| "negative"
+	| "polaroid"
+	| "vintage"
+	| "lsd"
+	| "predator"
+	| "kodachrome"
+	| "browni"
+	| "technicolor"
+	| "blackAndWhite"
+	| "tint"
+	| "saturate"
+	| "brightness"
+	| "contrast"
+	| "hue"
+	| "night";
+
+/**
+ * 单条 filter spec — 各类型共用的字段池,只读自己关心的字段。
+ */
+export interface FilterSpec {
+	type: FilterType;
+	enabled?: boolean;
+
+	// BlurFilter
+	strength?: number;
+	quality?: number;
+	blurX?: number;
+	blurY?: number;
+
+	// ColorMatrixFilter
+	preset?: ColorMatrixPreset;
+	presetArg?: number;
+	matrix?: number[];
+
+	// DisplacementFilter
+	resource?: string;
+	scaleX?: number;
+	scaleY?: number;
+
+	// NoiseFilter
+	noise?: number;
+	seed?: number;
+	noiseAnimSpeed?: number;
+
+	// AlphaFilter
+	alpha?: number;
+}
+
+export interface FilterParams {
+	filters?: FilterSpec[];
+	filterArea?: { x: number; y: number; width: number; height: number };
+}
+
+/**
+ * Filter 组件
+ *
+ * 给挂载它的 GameObject 应用一组 PixiJS 内置 2D 滤镜:Blur / ColorMatrix / Displacement / Noise / Alpha。
+ * 实现层是 PixiJS DisplayObject.filters 数组,FilterSystem 把 spec 实例化为 PixiJS Filter 实例并绑到容器上。
+ *
+ * @example
+ * ```typescript
+ * sprite.addComponent(new Filter({
+ *   filters: [
+ *     { type: "blur", strength: 8 },
+ *     { type: "colorMatrix", preset: "sepia" },
+ *   ],
+ * }));
+ * ```
+ */
+export default class Filter extends Component<FilterParams> {
+	static componentName: string = "Filter";
+
+	filters: FilterSpec[] = [];
+	filterArea: FilterParams["filterArea"] | null = null;
+
+	init(params?: FilterParams) {
+		if (params) {
+			this.filters = params.filters ?? [];
+			this.filterArea = params.filterArea ?? null;
+		}
+	}
+}

package/lib/filters/alpha.ts

@@ -0,0 +1,6 @@
+import { AlphaFilter } from "pixi.js";
+import type { FilterSpec } from "../component";
+
+export function createAlphaFilter(spec: FilterSpec): AlphaFilter {
+	return new AlphaFilter({ alpha: spec.alpha ?? 1 } as any);
+}

package/lib/filters/blur.ts

@@ -0,0 +1,13 @@
+import { BlurFilter } from "pixi.js";
+import type { FilterSpec } from "../component";
+
+export function createBlurFilter(spec: FilterSpec): BlurFilter {
+	const strength = spec.strength ?? 8;
+	const opts: any = {
+		strength,
+		quality: spec.quality ?? 4,
+	};
+	if (spec.blurX != null) opts.strengthX = spec.blurX;
+	if (spec.blurY != null) opts.strengthY = spec.blurY;
+	return new BlurFilter(opts);
+}

package/lib/filters/colorMatrix.ts

@@ -0,0 +1,31 @@
+import { ColorMatrixFilter } from "pixi.js";
+import type { FilterSpec } from "../component";
+
+export function createColorMatrixFilter(spec: FilterSpec): ColorMatrixFilter {
+	const cm = new ColorMatrixFilter();
+	if (spec.matrix && spec.matrix.length === 20) {
+		(cm as any).matrix = spec.matrix as any;
+		return cm;
+	}
+	const arg = spec.presetArg ?? 1;
+	switch (spec.preset) {
+		case "sepia": (cm as any).sepia(true); break;
+		case "grayscale": (cm as any).greyscale(arg, true); break;
+		case "negative": (cm as any).negative(true); break;
+		case "polaroid": (cm as any).polaroid(true); break;
+		case "vintage": (cm as any).vintage(true); break;
+		case "lsd": (cm as any).lsd(true); break;
+		case "predator": (cm as any).predator(arg, true); break;
+		case "kodachrome": (cm as any).kodachrome(true); break;
+		case "browni": (cm as any).browni(true); break;
+		case "technicolor": (cm as any).technicolor(true); break;
+		case "blackAndWhite": (cm as any).blackAndWhite(true); break;
+		case "tint": (cm as any).tint(arg, true); break;
+		case "saturate": (cm as any).saturate(arg, true); break;
+		case "brightness": (cm as any).brightness(arg, true); break;
+		case "contrast": (cm as any).contrast(arg, true); break;
+		case "hue": (cm as any).hue(arg * 360, true); break;
+		case "night": (cm as any).night(arg, true); break;
+	}
+	return cm;
+}

package/lib/filters/displacement.ts

@@ -0,0 +1,27 @@
+import { DisplacementFilter, Sprite, Texture } from "pixi.js";
+import { resource } from "@eva/eva.js";
+import type { FilterSpec } from "../component";
+
+/**
+ * Build a DisplacementFilter from FilterSpec.
+ * Pulls the displacement texture from the Eva.js resource registry.
+ * If the resource isn't ready yet, returns a no-op filter (caller can later swap).
+ */
+export function createDisplacementFilter(spec: FilterSpec): DisplacementFilter {
+	const scale = { x: spec.scaleX ?? 20, y: spec.scaleY ?? 20 };
+	let sprite: Sprite;
+	if (spec.resource) {
+		const res = (resource as any).getResource?.(spec.resource);
+		const data = res?.data ?? res?.instance ?? null;
+		const tex: Texture | null =
+			data?.texture instanceof Texture
+				? data.texture
+				: data?.image
+					? Texture.from(data.image)
+					: null;
+		sprite = new Sprite(tex ?? Texture.EMPTY);
+	} else {
+		sprite = new Sprite(Texture.EMPTY);
+	}
+	return new DisplacementFilter({ sprite, scale });
+}

package/lib/filters/noise.ts

@@ -0,0 +1,9 @@
+import { NoiseFilter } from "pixi.js";
+import type { FilterSpec } from "../component";
+
+export function createNoiseFilter(spec: FilterSpec): NoiseFilter {
+	return new NoiseFilter({
+		noise: spec.noise ?? 0.5,
+		seed: spec.seed ?? Math.random(),
+	} as any);
+}

package/lib/index.ts

@@ -0,0 +1,3 @@
+export { default as Filter } from "./component";
+export { default as FilterSystem } from "./system";
+export type { FilterParams, FilterSpec, FilterType, ColorMatrixPreset } from "./component";

package/lib/system.ts

@@ -0,0 +1,137 @@
+import {
+	GameObject,
+	decorators,
+	ComponentChanged,
+	OBSERVER_TYPE,
+} from "@eva/eva.js";
+import { ContainerManager, RendererSystem, Renderer } from "@eva/plugin-renderer";
+import type { Filter as PIXIFilter, Rectangle } from "pixi.js";
+import FilterComponent, { FilterSpec } from "./component";
+import { createBlurFilter } from "./filters/blur";
+import { createColorMatrixFilter } from "./filters/colorMatrix";
+import { createDisplacementFilter } from "./filters/displacement";
+import { createNoiseFilter } from "./filters/noise";
+import { createAlphaFilter } from "./filters/alpha";
+
+interface BoundFilter {
+	pixiFilters: PIXIFilter[];
+	specs: FilterSpec[];
+}
+
+@decorators.componentObserver({
+	Filter: [
+		{ prop: ["filters"], deep: true },
+		{ prop: ["filterArea"], deep: true },
+	],
+})
+export default class FilterSystem extends Renderer {
+	name: string = "FilterSystem";
+	containerManager: ContainerManager;
+	renderSystem: RendererSystem;
+
+	private bound: Map<number, BoundFilter> = new Map();
+	private elapsed = 0;
+
+	init() {
+		this.renderSystem = this.game.getSystem(RendererSystem) as RendererSystem;
+		this.renderSystem.rendererManager.register(this);
+	}
+
+	rendererUpdate(_gameObject: GameObject) {
+		// no-op (filters are static; filterArea applied on change only)
+	}
+
+	componentChanged(changed: ComponentChanged) {
+		if (changed.componentName !== "Filter") return;
+		const id = changed.gameObject.id;
+
+		if (changed.type === OBSERVER_TYPE.REMOVE) {
+			this.removeFilters(id);
+			return;
+		}
+
+		// ADD or CHANGE
+		this.applyFilters(changed.gameObject, changed.component as FilterComponent);
+	}
+
+	private applyFilters(go: GameObject, component: FilterComponent) {
+		const container = this.containerManager.getContainer(go.id);
+		if (!container) return;
+
+		// Dispose existing
+		this.disposeBound(go.id);
+
+		const specs: FilterSpec[] = (component.filters || []).filter(
+			(s) => s.enabled !== false,
+		);
+		const pixiFilters = specs.map((s) => this.createOne(s)).filter(Boolean) as PIXIFilter[];
+
+		(container as any).filters = pixiFilters;
+
+		if (component.filterArea) {
+			const fa = component.filterArea;
+			(container as any).filterArea = { x: fa.x, y: fa.y, width: fa.width, height: fa.height } as Rectangle;
+		} else {
+			(container as any).filterArea = null;
+		}
+
+		this.bound.set(go.id, { pixiFilters, specs });
+	}
+
+	private removeFilters(id: number) {
+		const container = this.containerManager.getContainer(id);
+		if (container) {
+			(container as any).filters = null;
+			(container as any).filterArea = null;
+		}
+		this.disposeBound(id);
+	}
+
+	private disposeBound(id: number) {
+		const b = this.bound.get(id);
+		if (!b) return;
+		for (const f of b.pixiFilters) {
+			try {
+				(f as any).destroy?.();
+			} catch {
+				/* ignore */
+			}
+		}
+		this.bound.delete(id);
+	}
+
+	private createOne(spec: FilterSpec): PIXIFilter | null {
+		switch (spec.type) {
+			case "blur":
+				return createBlurFilter(spec) as unknown as PIXIFilter;
+			case "colorMatrix":
+				return createColorMatrixFilter(spec) as unknown as PIXIFilter;
+			case "displacement":
+				return createDisplacementFilter(spec) as unknown as PIXIFilter;
+			case "noise":
+				return createNoiseFilter(spec) as unknown as PIXIFilter;
+			case "alpha":
+				return createAlphaFilter(spec) as unknown as PIXIFilter;
+			default:
+				return null;
+		}
+	}
+
+	update(time?: { deltaTime: number }) {
+		// Drain componentObserver so componentChanged fires for ADD/CHANGE/REMOVE.
+		super.update(time as any);
+
+		// Animate noise seed for filters with noiseAnimSpeed
+		const dt = (time?.deltaTime ?? 16) / 1000;
+		this.elapsed += dt;
+		for (const { pixiFilters, specs } of this.bound.values()) {
+			for (let i = 0; i < specs.length; i++) {
+				const s = specs[i];
+				if (s.type === "noise" && s.noiseAnimSpeed) {
+					const f = pixiFilters[i] as any;
+					if (f) f.seed = (this.elapsed * s.noiseAnimSpeed) % 1;
+				}
+			}
+		}
+	}
+}

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@eva/plugin-renderer-filter",
+  "version": "2.1.0-beta.1",
+  "description": "@eva/plugin-renderer-filter — wraps PixiJS built-in 2D filters (Blur/ColorMatrix/Displacement/Noise/Alpha) as Eva.js components.",
+  "main": "lib/index.ts",
+  "module": "lib/index.ts",
+  "types": "lib/index.ts",
+  "files": [
+    "lib"
+  ],
+  "keywords": [
+    "eva.js"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@eva/eva.js": "2.1.0-beta.1",
+    "@eva/inspector-decorator": "^2.0.0-beta.0",
+    "@eva/plugin-renderer": "2.1.0-beta.1",
+    "pixi.js": "^8.17.0"
+  }
+}