EffectsFacade — 效果子门面

通过 app.effects 访问 3D 场景效果管理。

add(type, options)

添加效果。

add(type: string, options?: object): EffectRef

参数	类型	描述
type	string	效果类型（如 'bloom'、'fog'、'glow'）
options	object	类型对应的选项

返回值：EffectRef，每次调用生成唯一 ID。

const fx = app.effects.add('bloom');
// fx.id 形如 'fx_1'

const fog = app.effects.add('fog', { density: 0.5 });

get(id)

获取效果引用。

get(id: string): EffectRef | null

const fx = app.effects.get('fx_1');
if (fx) {
  fx.setEnabled(false);
}

list()

列出所有效果。

list(): EffectRef[]

const effects = app.effects.list();
effects.forEach(fx => console.log(fx.id));

remove(idOrRef)

移除效果。

remove(idOrRef: string | EffectRef): void

接受字符串 ID 或 EffectRef 对象。

app.effects.remove('fx_1');
// 或
app.effects.remove(fxRef);

setLighting(options)

设置场景光照。

setLighting(options?: { sunPosition?: Coordinate | 'now'; shadows?: boolean; ambient?: string }): this

参数	类型	描述
sunPosition	Coordinate | 'now'	太阳位置坐标或 'now'（当前时间）
shadows	boolean	是否启用阴影
ambient	string	环境光颜色

app.effects.setLighting({ sunPosition: 'now', shadows: true, ambient: '#ffffff' });

// 指定太阳位置
app.effects.setLighting({ sunPosition: [116, 39] });

setClipping(planes)

设置裁剪平面。

setClipping(planes: Array<{ normal: [number, number, number]; distance: number }> | null): this

参数	类型	描述
planes	Array | null	裁剪平面数组，或 null 移除所有裁剪

每个平面包含：

字段	类型	说明
normal	[number, number, number]	平面法向量
distance	number	到原点的距离

app.effects.setClipping([
  { normal: [0, 0, 1], distance: 100 },
]);

// 移除裁剪
app.effects.setClipping(null);

EffectRef

效果引用对象：

属性/方法	类型	说明
id	string	效果唯一标识
setEnabled(enabled)	EffectRef	启用/禁用效果（链式）
remove()	void	移除自身

fx.setEnabled(false);   // 禁用
fx.setEnabled(true);    // 启用
fx.remove();            // 移除