bplinejs 0.0.101-beta.10

package/lib/Material/shaders/line/fragment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fragment.js","names":[],"sources":[],"mappings":""}

package/lib/Material/shaders/line/vertex.js

@@ -0,0 +1,6 @@
+//#region src/scripts/Material/shaders/line/vertex.shader?raw
+var vertex_default = "\n// 深度来自队列层级，而不是提交顺序。矩阵和样式数组不因倒序绘制而搬动。\nstruct DrawDepth {\n    base: u32,\n    count: u32,\n    reverse: u32,\n    _padding: u32,\n};\n@group(0) @binding(5) var<uniform> drawDepth: DrawDepth;\n\nfn ResolveIndex(index: u32) -> u32 {\n    return select(index, drawDepth.count - 1u - index, drawDepth.reverse != 0u);\n}\n\nfn GetDepth(index: u32) -> f32 {\n    // 24 位整数除以 2^24，depth32float 可以精确表示；实际深度避开清空值 1。\n    return 1.0 - f32(drawDepth.base + index + 1u) / 16777216.0;\n}\n\nstruct VertexInput {\n    @location(0) position: vec2f,\n    @builtin(instance_index) instanceIndex: u32,\n    // 当前 basic line 暂不使用法线，保留给后续线条效果。\n    @location(2) normal: vec2f,\n};\n\n// linePoints 与标准三角面共用 Mesh 和 Camera 矩阵缓冲。\n@group(0) @binding(0) var<storage, read> modelMatrices: array<mat3x3<f32>>;\n@group(0) @binding(1) var<uniform> viewMatrix: mat3x3<f32>;\n@group(0) @binding(2) var<uniform> orthogonalMatrix: mat3x3<f32>;\n\nstruct VertexOutput {\n    @builtin(position) position: vec4f,\n    @location(0) @interpolate(flat) instanceIndex: u32,\n};\n\n@vertex\nfn main(input: VertexInput) -> VertexOutput {\n    // 保留入口 builtin 原值；用独立编号读取矩阵、样式并传给片段阶段。\n    let resolvedIndex = ResolveIndex(input.instanceIndex);\n    let modelMatrix = modelMatrices[resolvedIndex];\n    let worldPosition = modelMatrix * vec3f(input.position, 1.0);\n    let viewPosition = viewMatrix * worldPosition;\n    let clipPosition = orthogonalMatrix * viewPosition;\n\n    var output: VertexOutput;\n    output.position = vec4f(clipPosition.xy, GetDepth(resolvedIndex), 1.0);\n    output.instanceIndex = resolvedIndex;\n    return output;\n}\n";
+//#endregion
+export { vertex_default as default };
+
+//# sourceMappingURL=vertex.js.map

package/lib/Material/shaders/line/vertex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vertex.js","names":[],"sources":[],"mappings":""}

package/lib/Mesh/index.d.ts

@@ -0,0 +1,154 @@
+import Group from "../Group";
+import Style from "../Style";
+import type { Geometry2d, Material2d } from "../global-types.ts";
+import type { GroupLike } from "../Group";
+import type { GeoData, GeometrySubscriber } from "../Geometry/Geo";
+import type { MaterialChange, MaterialSubscriber } from "../Material/Material";
+import type { TextureResource } from "../Texture/Layers";
+import type { VersionedMath } from "bpmatrixjs/Math";
+interface MeshLike extends GroupLike, GeometrySubscriber, MaterialSubscriber {
+    data: Geometry2d | undefined;
+    material: Material2d | undefined;
+    order: number;
+    style: Style | undefined;
+    readonly count: number;
+    readonly capacity: number;
+    readonly textures: readonly (TextureResource | undefined)[];
+    readonly matrixData: Float32Array<ArrayBuffer>;
+    readonly styleData: Float32Array<ArrayBuffer>;
+    readonly matrixVersion: number;
+    readonly styleVersion: number;
+    readonly geometryPending: boolean;
+    readonly materialPending: boolean;
+    updateInstanceData(): void;
+    dispose(): void;
+    init(data: Geometry2d, material: Material2d): this;
+}
+/**
+ * 网格对象
+ * 在组对象基础上增加几何数据和材质数据
+ * @class
+ */
+declare class Mesh extends Group implements MeshLike {
+    /**
+     * 对象类型
+     */
+    readonly type: string;
+    /**
+     * 几何数据
+     */
+    private _data;
+    /**
+     * 材质数据
+     */
+    private _material;
+    private _style;
+    protected _matrixVersion: number;
+    protected _styleVersion: number;
+    protected _stylePending: boolean;
+    protected _geometryPending: boolean;
+    protected _materialPending: boolean;
+    protected _disposed: boolean;
+    protected _matrixPending: boolean;
+    /** 普通 Mesh 只有一个实例，后续 IMesh 扩展时仍按实际数量绘制。 */
+    protected _count: number;
+    /** 当前有效绘制条数。 */
+    get count(): number;
+    /** 当前实例容量，普通 Mesh 不提前分配大量空槽。 */
+    protected _capacity: number;
+    /** 已分配槽数，不是扩容倍率。 */
+    get capacity(): number;
+    /** 连续实例矩阵，每实例 12 个 float（含 Mat3 对齐补位），由 updateInstanceData 写入。 */
+    protected _matrixData: Float32Array<ArrayBuffer>;
+    /** 连续世界矩阵数组，调用 updateInstanceData 后读取，不直接修改。 */
+    get matrixData(): Float32Array<ArrayBuffer>;
+    /** 连续实例样式，每实例 44 个 float，由 updateInstanceData 写入，不直接修改。 */
+    protected _styleData: Float32Array<ArrayBuffer>;
+    /** 连续样式数组，最后四个 float 保存三种贴图层号与补位。 */
+    get styleData(): Float32Array<ArrayBuffer>;
+    /** 普通 Mesh 每个分区只绑定一张图片，Shader 层号始终为 0。 */
+    get textures(): readonly (TextureResource | undefined)[];
+    /** Mesh 管理的样式；undefined 表示不接管 Geometry / Material 的样式。 */
+    get style(): Style | undefined;
+    /**
+     * 更换 Mesh 样式，并同步到当前几何和材质。
+     * undefined 仅停止接管，不清除它们已有的样式，也不销毁共享 Style。
+     * @param value 新样式引用
+     */
+    set style(value: Style | undefined);
+    /** 连续矩阵数据版本，各 Render 独立记录上传快照。 */
+    get matrixVersion(): number;
+    /** 连续样式数据版本，各 Render 独立记录上传快照。 */
+    get styleVersion(): number;
+    /** 几何通知待处理；生成和 GPU 上传仍归 geometryList，不在 Mesh 回调里执行。 */
+    get geometryPending(): boolean;
+    /** 材质通知待处理，用于下帧校验和更新 Mesh 自己的样式数组。 */
+    get materialPending(): boolean;
+    /**
+     * 几何发生变化，只标记本 Mesh 的绑定需要检查。
+     * @param geometry 通知来源；旧几何解绑后不再影响本 Mesh
+     */
+    onGeometryChange(geometry: GeoData): void;
+    /**
+     * 材质变化只安排下帧工作，不在通知链内上传 GPU 或递归改写 Style。
+     * @param change 样式数据和资源引用的影响范围
+     */
+    onMaterialChange(change: MaterialChange): void;
+    /** 最终停用 Mesh 时解绑资源；从 Scene 移除不会自动调用，也不销毁共享资源。 */
+    dispose(): void;
+    /** 将 Mesh 主动指定的样式同步给新绑定的几何及材质。 */
+    private syncStyle;
+    /**
+     * 世界矩阵计算完成后，将单实例数据打包到预分配数组。
+     * 数组不每帧分配；矩阵与样式分别更新版本，静止或只移动时不重复上传样式。
+     */
+    updateInstanceData(): void;
+    /**
+     * 世界矩阵完成修改后标记连续数组需要重打包，不再逐帧比较 12 个 float。
+     * @param source 数学对象
+     * @param field 关联字段
+     */
+    onMathChange(source: VersionedMath, field: string): void;
+    /**
+     * 获取当前几何体。
+     * @returns Geometry，未设置时为 undefined
+     */
+    get data(): Geometry2d | undefined;
+    /**
+     * 替换几何体，追加材质类型标记并刷新所在场景的资源引用。
+     * @param data 新几何体，undefined 表示暂不绘制
+     */
+    set data(data: Geometry2d | undefined);
+    /**
+     * 获取当前材质。
+     * @returns Material，未设置时为 undefined
+     */
+    get material(): Material2d | undefined;
+    /**
+     * 替换材质，追加当前几何类型标记并刷新场景引用。
+     * @param material 新材质，undefined 表示暂不绘制
+     */
+    set material(material: Material2d | undefined);
+    /**
+     * 同步材质几何类型与场景引用，不修改共享材质的着色器选择。
+     * @returns 无返回值
+     */
+    private updateResources;
+    /**
+     * 创建网格对象
+     * @param data 几何数据
+     * @param material 材质数据
+     * @param style true 创建全新 Style；false 保留资源各自样式；Style 指定共享样式
+     */
+    constructor(data: Geometry2d, material: Material2d, style?: Style | boolean);
+    /**
+     * 设置当前 Mesh 使用的 Geometry 与 Material。
+     * Mesh 已加入 Scene 时会标记场景结构变化，下次初始化将重建四个资源列表。
+     * @param data 几何数据
+     * @param material 材质数据
+     * @returns 当前 Mesh
+     */
+    init(data: Geometry2d, material: Material2d): this;
+}
+export default Mesh;
+export type { MeshLike };

package/lib/Mesh/index.js

@@ -0,0 +1,254 @@
+import { WriteStyleData } from "../Style/WriteStyleData.js";
+import Style from "../Style/index.js";
+import Group from "../Group/index.js";
+//#region src/scripts/Mesh/index.ts
+/**
+* 网格对象
+* 在组对象基础上增加几何数据和材质数据
+* @class
+*/
+var Mesh = class extends Group {
+	/**
+	* 对象类型
+	*/
+	type = "Mesh";
+	/**
+	* 几何数据
+	*/
+	_data;
+	/**
+	* 材质数据
+	*/
+	_material;
+	_style;
+	_matrixVersion = 0;
+	_styleVersion = 0;
+	_stylePending = true;
+	_geometryPending = true;
+	_materialPending = true;
+	_disposed = false;
+	_matrixPending = true;
+	/** 普通 Mesh 只有一个实例，后续 IMesh 扩展时仍按实际数量绘制。 */
+	_count = 1;
+	/** 当前有效绘制条数。 */
+	get count() {
+		return this._count;
+	}
+	/** 当前实例容量，普通 Mesh 不提前分配大量空槽。 */
+	_capacity = 1;
+	/** 已分配槽数，不是扩容倍率。 */
+	get capacity() {
+		return this._capacity;
+	}
+	/** 连续实例矩阵，每实例 12 个 float（含 Mat3 对齐补位），由 updateInstanceData 写入。 */
+	_matrixData = /* @__PURE__ */ new Float32Array(12);
+	/** 连续世界矩阵数组，调用 updateInstanceData 后读取，不直接修改。 */
+	get matrixData() {
+		return this._matrixData;
+	}
+	/** 连续实例样式，每实例 44 个 float，由 updateInstanceData 写入，不直接修改。 */
+	_styleData = /* @__PURE__ */ new Float32Array(44);
+	/** 连续样式数组，最后四个 float 保存三种贴图层号与补位。 */
+	get styleData() {
+		return this._styleData;
+	}
+	/** 普通 Mesh 每个分区只绑定一张图片，Shader 层号始终为 0。 */
+	get textures() {
+		const style = this.material?.style;
+		return [
+			style?.solid.texture,
+			style?.edge.texture,
+			style?.points.texture
+		];
+	}
+	/** Mesh 管理的样式；undefined 表示不接管 Geometry / Material 的样式。 */
+	get style() {
+		return this._style;
+	}
+	/**
+	* 更换 Mesh 样式，并同步到当前几何和材质。
+	* undefined 仅停止接管，不清除它们已有的样式，也不销毁共享 Style。
+	* @param value 新样式引用
+	*/
+	set style(value) {
+		if (this._disposed) throw new Error("Disposed mesh cannot be reused.");
+		if (this._style === value && (value === void 0 || (this._data === void 0 || this._data.style === value) && (this._material === void 0 || this._material.style === value))) return;
+		this._style = value;
+		this.syncStyle();
+		this.updateResources();
+	}
+	/** 连续矩阵数据版本，各 Render 独立记录上传快照。 */
+	get matrixVersion() {
+		return this._matrixVersion;
+	}
+	/** 连续样式数据版本，各 Render 独立记录上传快照。 */
+	get styleVersion() {
+		return this._styleVersion;
+	}
+	/** 几何通知待处理；生成和 GPU 上传仍归 geometryList，不在 Mesh 回调里执行。 */
+	get geometryPending() {
+		return this._geometryPending;
+	}
+	/** 材质通知待处理，用于下帧校验和更新 Mesh 自己的样式数组。 */
+	get materialPending() {
+		return this._materialPending;
+	}
+	/**
+	* 几何发生变化，只标记本 Mesh 的绑定需要检查。
+	* @param geometry 通知来源；旧几何解绑后不再影响本 Mesh
+	*/
+	onGeometryChange(geometry) {
+		if (!this._disposed && geometry === this._data) this._geometryPending = true;
+	}
+	/**
+	* 材质变化只安排下帧工作，不在通知链内上传 GPU 或递归改写 Style。
+	* @param change 样式数据和资源引用的影响范围
+	*/
+	onMaterialChange(change) {
+		if (this._disposed || change.source !== this._material) return;
+		this._materialPending = true;
+		this._stylePending ||= change.style;
+		if (change.resources) this.getScene(this)?.updateVersion();
+	}
+	/** 最终停用 Mesh 时解绑资源；从 Scene 移除不会自动调用，也不销毁共享资源。 */
+	dispose() {
+		super.dispose();
+		this._data?.delete(this);
+		this._material?.delete(this);
+		this._disposed = true;
+	}
+	/** 将 Mesh 主动指定的样式同步给新绑定的几何及材质。 */
+	syncStyle() {
+		if (this._style === void 0) return;
+		if (this._data !== void 0) this._data.style = this._style;
+		if (this._material !== void 0) this._material.style = this._style;
+	}
+	/**
+	* 世界矩阵计算完成后，将单实例数据打包到预分配数组。
+	* 数组不每帧分配；矩阵与样式分别更新版本，静止或只移动时不重复上传样式。
+	*/
+	updateInstanceData() {
+		if (this._disposed) throw new Error("Disposed mesh cannot be rendered.");
+		if (this._geometryPending && this._data !== void 0) this._material?.addGeometryType(this._data.type);
+		const matrix = this.worldMatrix.GPUData;
+		if (this._matrixPending) {
+			this.matrixData.set(matrix, 0);
+			this._matrixVersion++;
+			this._matrixPending = false;
+		}
+		if (this._stylePending) {
+			const style = this._material?.style;
+			if (style === void 0) this.styleData.fill(0);
+			else WriteStyleData(style, this.styleData, 0);
+			this._styleVersion++;
+			this._stylePending = false;
+		}
+		this._geometryPending = false;
+		this._materialPending = false;
+	}
+	/**
+	* 世界矩阵完成修改后标记连续数组需要重打包，不再逐帧比较 12 个 float。
+	* @param source 数学对象
+	* @param field 关联字段
+	*/
+	onMathChange(source, field) {
+		super.onMathChange(source, field);
+		if (!this._nodeDisposed && field === "worldMatrix" && source === this.worldMatrix) this._matrixPending = true;
+	}
+	/**
+	* 获取当前几何体。
+	* @returns Geometry，未设置时为 undefined
+	*/
+	get data() {
+		return this._data;
+	}
+	/**
+	* 替换几何体，追加材质类型标记并刷新所在场景的资源引用。
+	* @param data 新几何体，undefined 表示暂不绘制
+	*/
+	set data(data) {
+		if (this._disposed) throw new Error("Disposed mesh cannot be reused.");
+		if (this._data === data) return;
+		data?.add(this);
+		this._data?.delete(this);
+		this._data = data;
+		this._geometryPending = true;
+		this.syncStyle();
+		this.updateResources();
+	}
+	/**
+	* 获取当前材质。
+	* @returns Material，未设置时为 undefined
+	*/
+	get material() {
+		return this._material;
+	}
+	/**
+	* 替换材质，追加当前几何类型标记并刷新场景引用。
+	* @param material 新材质，undefined 表示暂不绘制
+	*/
+	set material(material) {
+		if (this._disposed) throw new Error("Disposed mesh cannot be reused.");
+		if (this._material === material) return;
+		material?.add(this);
+		this._material?.delete(this);
+		this._material = material;
+		this._materialPending = true;
+		this._stylePending = true;
+		this.syncStyle();
+		this.updateResources();
+	}
+	/**
+	* 同步材质几何类型与场景引用，不修改共享材质的着色器选择。
+	* @returns 无返回值
+	*/
+	updateResources() {
+		if (this._data !== void 0) this._material?.addGeometryType(this._data.type);
+		const scene = this.getScene(this);
+		if (scene !== void 0) {
+			scene.updateLists();
+			scene.updateVersion();
+		}
+	}
+	/**
+	* 创建网格对象
+	* @param data 几何数据
+	* @param material 材质数据
+	* @param style true 创建全新 Style；false 保留资源各自样式；Style 指定共享样式
+	*/
+	constructor(data, material, style = true) {
+		super(0, 0);
+		this._style = style === true ? new Style() : style === false ? void 0 : style;
+		this.init(data, material);
+	}
+	/**
+	* 设置当前 Mesh 使用的 Geometry 与 Material。
+	* Mesh 已加入 Scene 时会标记场景结构变化，下次初始化将重建四个资源列表。
+	* @param data 几何数据
+	* @param material 材质数据
+	* @returns 当前 Mesh
+	*/
+	init(data, material) {
+		if (this._disposed) throw new Error("Disposed mesh cannot be reused.");
+		if (data !== this._data) {
+			data.add(this);
+			this._data?.delete(this);
+		}
+		if (material !== this._material) {
+			material.add(this);
+			this._material?.delete(this);
+		}
+		this._data = data;
+		this._material = material;
+		this._geometryPending = true;
+		this._materialPending = true;
+		this._stylePending = true;
+		this.syncStyle();
+		this.updateResources();
+		return this;
+	}
+};
+//#endregion
+export { Mesh as default };
+
+//# sourceMappingURL=index.js.map

package/lib/Mesh/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/scripts/Mesh/index.ts"],"sourcesContent":["\nimport Group from \"../Group\";\nimport Style from \"../Style\";\nimport { STYLE_STRIDE, WriteStyleData } from \"../Style/WriteStyleData\";\nimport type { Geometry2d, Material2d } from \"../global-types.ts\";\nimport type { GroupLike } from \"../Group\";\nimport type { GeoData, GeometrySubscriber } from \"../Geometry/Geo\";\nimport type { MaterialChange, MaterialSubscriber } from \"../Material/Material\";\nimport type { TextureResource } from \"../Texture/Layers\";\nimport type { VersionedMath } from \"bpmatrixjs/Math\";\n\n\ninterface MeshLike extends GroupLike, GeometrySubscriber, MaterialSubscriber {\n    data: Geometry2d | undefined;\n    material: Material2d | undefined;\n    order: number;\n    style: Style | undefined;\n    readonly count: number;\n    readonly capacity: number;\n    readonly textures: readonly (TextureResource | undefined)[];\n    readonly matrixData: Float32Array<ArrayBuffer>;\n    readonly styleData: Float32Array<ArrayBuffer>;\n    readonly matrixVersion: number;\n    readonly styleVersion: number;\n    readonly geometryPending: boolean;\n    readonly materialPending: boolean;\n    updateInstanceData(): void;\n    dispose(): void;\n    init(data: Geometry2d, material: Material2d): this;\n}\n\n/**\n * 网格对象\n * 在组对象基础上增加几何数据和材质数据\n * @class\n */\nclass Mesh extends Group implements MeshLike {\n    /**\n     * 对象类型\n     */\n    public readonly type: string = \"Mesh\";\n    /**\n     * 几何数据\n     */\n    private _data: Geometry2d | undefined;\n\n    /**\n     * 材质数据\n     */\n    private _material: Material2d | undefined;\n    private _style: Style | undefined;\n    protected _matrixVersion: number = 0;\n    protected _styleVersion: number = 0;\n    protected _stylePending: boolean = true;\n    protected _geometryPending: boolean = true;\n    protected _materialPending: boolean = true;\n    protected _disposed: boolean = false;\n    protected _matrixPending: boolean = true;\n\n    /** 普通 Mesh 只有一个实例，后续 IMesh 扩展时仍按实际数量绘制。 */\n    protected _count: number = 1;\n    /** 当前有效绘制条数。 */\n    public get count(): number { return this._count; }\n    /** 当前实例容量，普通 Mesh 不提前分配大量空槽。 */\n    protected _capacity: number = 1;\n    /** 已分配槽数，不是扩容倍率。 */\n    public get capacity(): number { return this._capacity; }\n    /** 连续实例矩阵，每实例 12 个 float（含 Mat3 对齐补位），由 updateInstanceData 写入。 */\n    protected _matrixData: Float32Array<ArrayBuffer> = new Float32Array(12);\n    /** 连续世界矩阵数组，调用 updateInstanceData 后读取，不直接修改。 */\n    public get matrixData(): Float32Array<ArrayBuffer> { return this._matrixData; }\n    /** 连续实例样式，每实例 44 个 float，由 updateInstanceData 写入，不直接修改。 */\n    protected _styleData: Float32Array<ArrayBuffer> = new Float32Array(STYLE_STRIDE);\n    /** 连续样式数组，最后四个 float 保存三种贴图层号与补位。 */\n    public get styleData(): Float32Array<ArrayBuffer> { return this._styleData; }\n    /** 普通 Mesh 每个分区只绑定一张图片，Shader 层号始终为 0。 */\n    public get textures(): readonly (TextureResource | undefined)[] {\n        const style = this.material?.style;\n        return [style?.solid.texture, style?.edge.texture, style?.points.texture];\n    }\n\n    /** Mesh 管理的样式；undefined 表示不接管 Geometry / Material 的样式。 */\n    public get style(): Style | undefined { return this._style; }\n\n    /**\n     * 更换 Mesh 样式，并同步到当前几何和材质。\n     * undefined 仅停止接管，不清除它们已有的样式，也不销毁共享 Style。\n     * @param value 新样式引用\n     */\n    public set style(value: Style | undefined) {\n        if (this._disposed) throw new Error(\"Disposed mesh cannot be reused.\");\n        if (this._style === value && (value === undefined\n            || ((this._data === undefined || this._data.style === value)\n                && (this._material === undefined || this._material.style === value)))) return;\n        this._style = value;\n        this.syncStyle();\n        this.updateResources();\n    }\n\n    /** 连续矩阵数据版本，各 Render 独立记录上传快照。 */\n    public get matrixVersion(): number { return this._matrixVersion; }\n    /** 连续样式数据版本，各 Render 独立记录上传快照。 */\n    public get styleVersion(): number { return this._styleVersion; }\n    /** 几何通知待处理；生成和 GPU 上传仍归 geometryList，不在 Mesh 回调里执行。 */\n    public get geometryPending(): boolean { return this._geometryPending; }\n    /** 材质通知待处理，用于下帧校验和更新 Mesh 自己的样式数组。 */\n    public get materialPending(): boolean { return this._materialPending; }\n\n    /**\n     * 几何发生变化，只标记本 Mesh 的绑定需要检查。\n     * @param geometry 通知来源；旧几何解绑后不再影响本 Mesh\n     */\n    public onGeometryChange(geometry: GeoData): void {\n        if (!this._disposed && geometry === this._data) this._geometryPending = true;\n    }\n\n    /**\n     * 材质变化只安排下帧工作，不在通知链内上传 GPU 或递归改写 Style。\n     * @param change 样式数据和资源引用的影响范围\n     */\n    public onMaterialChange(change: MaterialChange): void {\n        if (this._disposed || change.source !== this._material) return;\n        this._materialPending = true;\n        this._stylePending ||= change.style;\n        if (change.resources) this.getScene(this)?.updateVersion();\n    }\n\n    /** 最终停用 Mesh 时解绑资源；从 Scene 移除不会自动调用，也不销毁共享资源。 */\n    public dispose(): void {\n        super.dispose();\n        this._data?.delete(this);\n        this._material?.delete(this);\n        this._disposed = true;\n    }\n\n    /** 将 Mesh 主动指定的样式同步给新绑定的几何及材质。 */\n    private syncStyle(): void {\n        if (this._style === undefined) return;\n        if (this._data !== undefined) this._data.style = this._style;\n        if (this._material !== undefined) this._material.style = this._style;\n    }\n\n    /**\n     * 世界矩阵计算完成后，将单实例数据打包到预分配数组。\n     * 数组不每帧分配；矩阵与样式分别更新版本，静止或只移动时不重复上传样式。\n     */\n    public updateInstanceData(): void {\n        if (this._disposed) throw new Error(\"Disposed mesh cannot be rendered.\");\n        if (this._geometryPending && this._data !== undefined) {\n            this._material?.addGeometryType(this._data.type);\n        }\n        const matrix = this.worldMatrix.GPUData;\n        if (this._matrixPending) {\n            this.matrixData.set(matrix, 0);\n            this._matrixVersion++;\n            this._matrixPending = false;\n        }\n        // 材质通过 add 通知所有 Mesh；不再每帧探测 Style 引用及版本。\n        if (this._stylePending) {\n            const style = this._material?.style;\n            if (style === undefined) this.styleData.fill(0);\n            else WriteStyleData(style, this.styleData, 0);\n            this._styleVersion++;\n            this._stylePending = false;\n        }\n        this._geometryPending = false;\n        this._materialPending = false;\n    }\n\n    /**\n     * 世界矩阵完成修改后标记连续数组需要重打包，不再逐帧比较 12 个 float。\n     * @param source 数学对象\n     * @param field 关联字段\n     */\n    public override onMathChange(source: VersionedMath, field: string): void {\n        super.onMathChange(source, field);\n        if (!this._nodeDisposed && field === \"worldMatrix\" && source === this.worldMatrix) {\n            this._matrixPending = true;\n        }\n    }\n\n\n    /**\n     * 获取当前几何体。\n     * @returns Geometry，未设置时为 undefined\n     */\n    public get data(): Geometry2d | undefined {\n        return this._data;\n    }\n\n    /**\n     * 替换几何体，追加材质类型标记并刷新所在场景的资源引用。\n     * @param data 新几何体，undefined 表示暂不绘制\n     */\n    public set data(data: Geometry2d | undefined) {\n        if (this._disposed) throw new Error(\"Disposed mesh cannot be reused.\");\n        if (this._data === data) {\n            return;\n        }\n        data?.add(this);\n        this._data?.delete(this);\n        this._data = data;\n        this._geometryPending = true;\n        this.syncStyle();\n        this.updateResources();\n    }\n\n    /**\n     * 获取当前材质。\n     * @returns Material，未设置时为 undefined\n     */\n    public get material(): Material2d | undefined {\n        return this._material;\n    }\n\n    /**\n     * 替换材质，追加当前几何类型标记并刷新场景引用。\n     * @param material 新材质，undefined 表示暂不绘制\n     */\n    public set material(material: Material2d | undefined) {\n        if (this._disposed) throw new Error(\"Disposed mesh cannot be reused.\");\n        if (this._material === material) {\n            return;\n        }\n        material?.add(this);\n        this._material?.delete(this);\n        this._material = material;\n        this._materialPending = true;\n        this._stylePending = true;\n        this.syncStyle();\n        this.updateResources();\n    }\n\n    /**\n     * 同步材质几何类型与场景引用，不修改共享材质的着色器选择。\n     * @returns 无返回值\n     */\n    private updateResources(): void {\n        if (this._data !== undefined) {\n            this._material?.addGeometryType(this._data.type);\n        }\n        const scene = this.getScene(this);\n        if (scene !== undefined) {\n            scene.updateLists();\n            scene.updateVersion();\n        }\n    }\n\n    /**\n     * 创建网格对象\n     * @param data 几何数据\n     * @param material 材质数据\n     * @param style true 创建全新 Style；false 保留资源各自样式；Style 指定共享样式\n     */\n    public constructor(data: Geometry2d, material: Material2d, style: Style | boolean = true) {\n        super(0, 0);\n        this._style = style === true ? new Style() : style === false ? undefined : style;\n        this.init(data, material);\n    }\n\n    /**\n     * 设置当前 Mesh 使用的 Geometry 与 Material。\n     * Mesh 已加入 Scene 时会标记场景结构变化，下次初始化将重建四个资源列表。\n     * @param data 几何数据\n     * @param material 材质数据\n     * @returns 当前 Mesh\n     */\n    public init(data: Geometry2d, material: Material2d): this {\n        if (this._disposed) throw new Error(\"Disposed mesh cannot be reused.\");\n        if (data !== this._data) {\n            data.add(this);\n            this._data?.delete(this);\n        }\n        if (material !== this._material) {\n            material.add(this);\n            this._material?.delete(this);\n        }\n        this._data = data;\n        this._material = material;\n        this._geometryPending = true;\n        this._materialPending = true;\n        this._stylePending = true;\n        this.syncStyle();\n        this.updateResources();\n\n        return this;\n    }\n}\nexport default Mesh;\nexport type { MeshLike };\n"],"mappings":"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"}

package/lib/Object/index.d.ts

@@ -0,0 +1,95 @@
+import { Vec2 } from "bpmatrixjs/Math/Vec2";
+import { Mat3 } from "bpmatrixjs/Math/Mat3";
+import type { MathSubscriber, VersionedMath } from "bpmatrixjs/Math";
+import type { AddObject } from "../global-types";
+interface ObjectNodeLike extends MathSubscriber {
+    readonly id: number;
+    readonly type: string;
+    readonly version: number;
+    parent: AddObject | null;
+    position: Vec2;
+    rotation: number;
+    scale: Vec2;
+    matrix: Mat3;
+    worldMatrix: Mat3;
+    order: number;
+    updateVersion(): void;
+    ensureMatrix(): Mat3;
+    ensureWorldMatrix(): Mat3;
+    updateMatrix(): Mat3;
+    updateWorldMatrix(): Mat3;
+    dispose(): void;
+}
+/** 场景节点变换基类：参数持有一个版本，计算结果和每个消费者各存处理快照。 */
+declare class ObjectNode implements ObjectNodeLike {
+    /** 全局节点 ID。 */
+    readonly id: number;
+    /** 节点类型。 */
+    readonly type: string;
+    private _version;
+    private _parent;
+    private _position;
+    private _rotation;
+    private _scale;
+    private _matrix;
+    private _worldMatrix;
+    private _order;
+    private _localSnapshot;
+    private _worldSnapshot;
+    private _parentSnapshot;
+    private _parentVersion;
+    private _writingMatrices;
+    protected _nodeDisposed: boolean;
+    /** @param x 初始 X 坐标 @param y 初始 Y 坐标 */
+    constructor(x: number, y: number);
+    /** 节点输入版本；计算快照不会清除或回退它。 */
+    get version(): number;
+    /** 手动使变换失效；普通 position/scale/rotation 修改已自动通知。 */
+    updateVersion(): void;
+    /** 父节点，场景树结构请通过 Group.add/remove 修改。 */
+    get parent(): AddObject | null;
+    /** @param value 父引用，Group 维护 children 与 Scene 列表 */
+    set parent(value: AddObject | null);
+    /** 位置向量，内部 set/setX/x 赋值均能通知。 */
+    get position(): Vec2;
+    /** @param value 新位置向量，替换时解绑旧字段 */
+    set position(value: Vec2);
+    /** 本地旋转弧度。 */
+    get rotation(): number;
+    /** @param value 新旋转弧度 */
+    set rotation(value: number);
+    /** 缩放向量，可与其他节点共享。 */
+    get scale(): Vec2;
+    /** @param value 新缩放向量 */
+    set scale(value: Vec2);
+    /** 本地矩阵；直接修改类方法会作为自定义矩阵保留，直到变换参数再次改变。 */
+    get matrix(): Mat3;
+    /** @param value 新本地矩阵 */
+    set matrix(value: Mat3);
+    /** 世界矩阵，Mat3 通知用于更新 Mesh 连续矩阵数组。 */
+    get worldMatrix(): Mat3;
+    /** @param value 新世界矩阵 */
+    set worldMatrix(value: Mat3);
+    /**
+     * 数学对象完成修改后通知节点；内部计算不反向增加输入版本。
+     * @param source 数学对象
+     * @param field position/scale/matrix/worldMatrix 关联字段
+     */
+    onMathChange(source: VersionedMath, field: string): void;
+    /** 参数版本改变后才生成本地矩阵。 */
+    ensureMatrix(): Mat3;
+    /** 强制根据 position/rotation/scale 生成本地矩阵；覆盖手动指定的本地矩阵。 */
+    updateMatrix(): Mat3;
+    /** 先更新祖先，再按自身版本、父矩阵身份和版本更新世界矩阵，不遍历兄弟节点。 */
+    ensureWorldMatrix(): Mat3;
+    /** 强制重新计算当前世界矩阵，同时保留显式修改的本地矩阵。 */
+    updateWorldMatrix(): Mat3;
+    /** 绘制排序值。 */
+    get order(): number;
+    /** @param value 新排序值；所属 Scene 递增版本，下一帧重排列表 */
+    set order(value: number);
+    /** 最终释放数学对象订阅，不移除场景节点，不销毁共享 Vec2/Mat3。 */
+    dispose(): void;
+}
+export default ObjectNode;
+export type { ObjectNodeLike };