From 4e305e392ac9b49e9b099a00574587c427b5d856 Mon Sep 17 00:00:00 2001
From: unanmed <1319491857@qq.com>
Date: Mon, 21 Sep 2026 19:16:33 +0800
Subject: [PATCH] refactor(type): material types.

---
 packages-user/client-base/src/load/loader.ts  |  4 +-
 .../client-base/src/material/autotile.ts      |  4 +-
 .../client-base/src/material/builder.ts       |  6 +-
 .../client-base/src/material/manager.ts       |  4 +-
 .../client-base/src/material/types.ts         | 68 ++++---------------
 .../client-base/src/material/utils.ts         |  6 ++
 packages-user/client-base/src/types.ts        |  9 ++-
 packages-user/client-modules/package.json     |  2 +
 packages-user/client-modules/src/client.ts    |  4 +-
 .../client-modules/src/fallback/load.ts       |  4 +-
 .../client-modules/src/render/map/moving.ts   |  4 +-
 .../client-modules/src/render/map/renderer.ts |  4 +-
 .../client-modules/src/render/map/types.ts    |  4 +-
 packages-user/client-modules/src/types.ts     | 10 +--
 packages-user/client-system/package.json      |  6 ++
 packages-user/client-system/src/index.ts      |  1 +
 packages-user/client-system/src/types.ts      |  8 +++
 packages-user/data-state/src/types.ts         |  7 +-
 pnpm-lock.yaml                                | 12 ++++
 19 files changed, 80 insertions(+), 87 deletions(-)
 create mode 100644 packages-user/client-system/package.json
 create mode 100644 packages-user/client-system/src/index.ts
 create mode 100644 packages-user/client-system/src/types.ts

diff --git a/packages-user/client-base/src/load/loader.ts b/packages-user/client-base/src/load/loader.ts
index f3599e5..c9a906c 100644
--- a/packages-user/client-base/src/load/loader.ts
+++ b/packages-user/client-base/src/load/loader.ts
@@ -22,7 +22,7 @@ import {
 } from '@user/data-base';
 import { IMotaAudioContext, ISoundPlayer } from '@motajs/audio';
 import { loading } from '@user/data-base';
-import { IMaterialManager } from '../material';
+import { ITextureManager } from '../material';
 import { ITextureSplitter, Texture, TextureRowSplitter } from '@motajs/render';
 import { iconNames } from './data';
 import { IMotaDataLoader } from '@user/data-base';
@@ -55,7 +55,7 @@ export class MotaAssetsLoader implements IMotaAssetsLoader {
         private readonly dataLoader: IMotaDataLoader,
         private readonly ac: IMotaAudioContext,
         private readonly sounds: ISoundPlayer<SoundIds>,
-        private readonly materials: IMaterialManager
+        private readonly materials: ITextureManager
     ) {
         this.imageProcessor = new LoadImageProcessor();
         this.audioProcessor = new LoadAudioProcessor(ac);
diff --git a/packages-user/client-base/src/material/autotile.ts b/packages-user/client-base/src/material/autotile.ts
index fe28761..f4d0042 100644
--- a/packages-user/client-base/src/material/autotile.ts
+++ b/packages-user/client-base/src/material/autotile.ts
@@ -10,7 +10,7 @@ import {
     IAutotileConnection,
     IAutotileProcessor,
     IMaterialFramedData,
-    IMaterialManager
+    ITextureManager
 } from './types';
 import { isNil } from 'lodash-es';
 
@@ -45,7 +45,7 @@ export class AutotileProcessor implements IAutotileProcessor {
     /** 自动元件父子关系映射，父元件 -> 子元件列表 */
     readonly childMap: Map<number, Set<number>> = new Map();
 
-    constructor(readonly manager: IMaterialManager) {}
+    constructor(readonly manager: ITextureManager) {}
 
     private ensureChildSet(num: number) {
         const set = this.childMap.get(num);
diff --git a/packages-user/client-base/src/material/builder.ts b/packages-user/client-base/src/material/builder.ts
index b030b52..3797688 100644
--- a/packages-user/client-base/src/material/builder.ts
+++ b/packages-user/client-base/src/material/builder.ts
@@ -6,7 +6,7 @@ import {
     TextureMaxRectsStreamComposer,
     SizedCanvasImageSource
 } from '@motajs/render';
-import { IAssetBuilder, IMaterialGetter, ITrackedAssetData } from './types';
+import { IAssetBuilder, ITextureGetter, ITrackedAssetData } from './types';
 import { logger, PrivateListDirtyTracker } from '@motajs/common';
 
 export class AssetBuilder implements IAssetBuilder {
@@ -24,7 +24,7 @@ export class AssetBuilder implements IAssetBuilder {
     /** 贴图更新的 promise */
     private pending: Promise<void> = Promise.resolve();
 
-    constructor(readonly materials: IMaterialGetter) {
+    constructor(readonly materials: ITextureGetter) {
         this.trackedData = new TrackedAssetData(materials, this);
     }
 
@@ -108,7 +108,7 @@ class TrackedAssetData
     private promises: Set<Promise<ImageBitmap>> = new Set();
 
     constructor(
-        readonly materials: IMaterialGetter,
+        readonly materials: ITextureGetter,
         readonly builder: AssetBuilder
     ) {
         super(0);
diff --git a/packages-user/client-base/src/material/manager.ts b/packages-user/client-base/src/material/manager.ts
index 85c92d0..3062323 100644
--- a/packages-user/client-base/src/material/manager.ts
+++ b/packages-user/client-base/src/material/manager.ts
@@ -13,7 +13,7 @@ import {
 import {
     IBlockIdentifier,
     IMaterialData,
-    IMaterialManager,
+    ITextureManager,
     IIndexedIdentifier,
     IMaterialAssetData,
     BlockCls,
@@ -35,7 +35,7 @@ interface TilesetCache {
     readonly texture: ITexture;
 }
 
-export class MaterialManager implements IMaterialManager {
+export class MaterialManager implements ITextureManager {
     readonly tileStore: ITextureStore = new TextureStore();
     readonly tilesetStore: ITextureStore = new TextureStore();
     readonly imageStore: ITextureStore = new TextureStore();
diff --git a/packages-user/client-base/src/material/types.ts b/packages-user/client-base/src/material/types.ts
index ebe3404..7c8f0e1 100644
--- a/packages-user/client-base/src/material/types.ts
+++ b/packages-user/client-base/src/material/types.ts
@@ -6,6 +6,7 @@ import {
     ITextureStore,
     SizedCanvasImageSource
 } from '@motajs/render';
+import { ICoreStateExtended } from '@user/data-state';
 
 export const enum BlockCls {
     Unknown,
@@ -81,13 +82,6 @@ export interface IAutotileConnection {
     readonly center: number;
 }
 
-export interface IBigImageReturn {
-    /** 大怪物贴图在 store 中的标识符 */
-    readonly identifier: number;
-    /** 存储大怪物贴图的存储对象 */
-    readonly store: ITextureStore;
-}
-
 export interface IMaterialFramedData {
     /** 贴图对象 */
     texture: ITexture;
@@ -107,9 +101,9 @@ export interface IMaterialAsset
     readonly data: ITextureComposedData;
 }
 
-export interface IAutotileProcessor {
+export interface IAutotileProcessor extends ICoreStateExtended {
     /** 该自动元件处理器使用的素材管理器 */
-    readonly manager: IMaterialManager;
+    readonly manager: ITextureManager;
 
     /**
      * 设置一个自动元件的特殊连接方式，设置后当前自动元件将会单方面与目标元件连接，
@@ -199,7 +193,7 @@ export interface IAutotileProcessor {
     ): Generator<ITextureRenderable, void>;
 }
 
-export interface IMaterialGetter {
+export interface ITextureGetter {
     /**
      * 根据图块数字获取图块，可以获取额外素材，会自动将未缓存的额外素材缓存
      * @param identifier 图块的图块数字
@@ -212,25 +206,6 @@ export interface IMaterialGetter {
      */
     getBlockCls(identifier: number): BlockCls;
 
-    /**
-     * 判断一个图块是否包含 `bigImage` 贴图，即是否是大怪物
-     * @param identifier 图块标识符，即图块数字
-     */
-    isBigImage(identifier: number): boolean;
-
-    /**
-     * 根据图块标识符获取一个图块的 `bigImage` 贴图
-     * @param identifier 图块标识符，即图块数字
-     */
-    getBigImage(identifier: number): Readonly<IMaterialFramedData> | null;
-
-    /**
-     * 根据图块标识符，首先判断是否是 `bigImage` 贴图，如果是，则返回 `bigImage` 贴图，
-     * 否则返回普通贴图。如果图块不存在，则返回 `null`
-     * @param identifier 图块标识符，即图块数字
-     */
-    getIfBigImage(identifier: number): Readonly<IMaterialFramedData> | null;
-
     /**
      * 根据标识符获取图集信息
      * @param identifier 图集的标识符
@@ -250,7 +225,7 @@ export interface IMaterialGetter {
     getImage(identifier: number): ITexture | null;
 }
 
-export interface IMaterialAliasGetter {
+export interface ITextureAliasGetter {
     /**
      * 根据图块 id 获取图块，可以获取额外素材，会自动将未缓存的额外素材缓存
      * @param alias 图块 id
@@ -280,16 +255,12 @@ export interface IMaterialAliasGetter {
      * @param alias 图块别名，即图块的 id
      */
     getBlockClsByAlias(alias: string): BlockCls;
-
-    /**
-     * 根据图块别名获取一个图块的 `bigImage` 贴图
-     * @param alias 图块别名，即图块的 id
-     */
-    getBigImageByAlias(alias: string): Readonly<IMaterialFramedData> | null;
 }
 
-export interface IMaterialManager
-    extends IMaterialGetter, IMaterialAliasGetter {
+export interface ITextureManager
+    extends ITextureGetter, ITextureAliasGetter, ICoreStateExtended {
+    /** 通过加载获取的所有纹理贴图存储，包括图块、普通图片等 */
+    readonly textures: ITextureStore;
     /** 贴图存储，把 terrains 等内容单独分开存储 */
     readonly tileStore: ITextureStore;
     /** tilesets 贴图存储，每个 tileset 是一个贴图对象 */
@@ -298,8 +269,6 @@ export interface IMaterialManager
     readonly imageStore: ITextureStore;
     /** 图集存储，将常用贴图存入其中 */
     readonly assetStore: ITextureStore;
-    /** bigImage 存储，存储大怪物数据 */
-    readonly bigImageStore: ITextureStore;
 
     /** 图集信息存储 */
     readonly assetDataStore: Iterable<[number, ITextureComposedData]>;
@@ -445,18 +414,6 @@ export interface IMaterialManager
      */
     getAliasByIdentifier(identifier: number): string | undefined;
 
-    /**
-     * 设置一个图块的 `bigImage` 贴图，即大怪物贴图，但不止怪物能用
-     * @param identifier 图块标识符，即图块数字
-     * @param image `bigImage` 对应的贴图对象
-     * @param frames `bigImage` 的帧数，即贴图有多少帧
-     */
-    setBigImage(
-        identifier: number,
-        image: ITexture,
-        frames: number
-    ): IBigImageReturn;
-
     /**
      * 当前的所有图集中是否包含指定的贴图对象
      * @param texture 贴图对象
@@ -470,7 +427,7 @@ export interface IMaterialManager
     getTextureAsset(texture: ITexture): number | undefined;
 }
 
-export interface IAssetBuilder {
+export interface IAssetBuilder extends ICoreStateExtended {
     /**
      * 将图集打包器输出至指定贴图存储对象，只能输出到一个存储对象中，设置多个仅最后一个有效
      * @param store 贴图存储对象
@@ -502,7 +459,8 @@ export interface IAssetBuilder {
     close(): void;
 }
 
-export interface ITrackedAssetData extends IDirtyTracker<Set<number>> {
+export interface ITrackedAssetData
+    extends IDirtyTracker<Set<number>>, ICoreStateExtended {
     /** 图像源列表 */
     readonly sourceList: Map<number, ImageBitmap>;
     /**
@@ -511,7 +469,7 @@ export interface ITrackedAssetData extends IDirtyTracker<Set<number>> {
      */
     readonly skipRef: Map<SizedCanvasImageSource, number>;
     /** 贴图数据 */
-    readonly materials: IMaterialGetter;
+    readonly materials: ITextureGetter;
 
     /**
      * 取消使用此图集，释放相关资源
diff --git a/packages-user/client-base/src/material/utils.ts b/packages-user/client-base/src/material/utils.ts
index cbec1ed..8622ad1 100644
--- a/packages-user/client-base/src/material/utils.ts
+++ b/packages-user/client-base/src/material/utils.ts
@@ -1,6 +1,9 @@
 import { ITexture } from '@motajs/render';
 import { BlockCls } from './types';
 
+/**
+ * @deprecated 后续理应不需要此接口
+ */
 export function getClsByString(cls: Cls): BlockCls {
     switch (cls) {
         case 'terrains':
@@ -26,6 +29,9 @@ export function getClsByString(cls: Cls): BlockCls {
     }
 }
 
+/**
+ * @deprecated 后续应对存储结构进行重构，每个 tile 都可以自定义帧数
+ */
 export function getTextureFrame(cls: BlockCls, texture: ITexture) {
     switch (cls) {
         case BlockCls.Animates:
diff --git a/packages-user/client-base/src/types.ts b/packages-user/client-base/src/types.ts
index 4a48b7a..8119921 100644
--- a/packages-user/client-base/src/types.ts
+++ b/packages-user/client-base/src/types.ts
@@ -1,8 +1,9 @@
 import { IBGMPlayer, IMotaAudioContext, ISoundPlayer } from '@motajs/audio';
 import { ISaveSystem } from './save';
 import { ICoreState } from '@user/data-state';
-import { IAutotileProcessor, IMaterialManager } from './material';
+import { IAutotileProcessor, ITextureManager } from './material';
 import { IRenderTreeRoot } from '@motajs/render';
+import { IExcitation, IExcitationDivider } from '@motajs/animate';
 
 export interface IClientBase extends ICoreState {
     /** 存档系统 */
@@ -14,11 +15,15 @@ export interface IClientBase extends ICoreState {
     /** BGM 播放器 */
     readonly bgmPlayer: IBGMPlayer<BgmIds>;
     /** 素材管理器 */
-    readonly materials: IMaterialManager;
+    readonly materials: ITextureManager;
     /** 自动元件处理器 */
     readonly autotile: IAutotileProcessor;
     /** 渲染画面的根元素 */
     readonly renderer: IRenderTreeRoot;
+    /** 用于渲染系统的 Raf 激励源 */
+    readonly rafExcitation: IExcitation<number>;
+    /** 用于渲染系统的激励源分频器 */
+    readonly excitationDivider: IExcitationDivider<number>;
 }
 
 export interface IClientBaseExtended {
diff --git a/packages-user/client-modules/package.json b/packages-user/client-modules/package.json
index b2a97bb..573de78 100644
--- a/packages-user/client-modules/package.json
+++ b/packages-user/client-modules/package.json
@@ -10,6 +10,8 @@
         "@motajs/legacy-ui": "workspace:*",
         "@motajs/types": "workspace:*",
         "@motajs/system": "workspace:*",
+        "@user/client-base": "workspace:*",
+        "@user/client-system": "workspace:*",
         "@user/data-common": "workspace:*",
         "@user/data-base": "workspace:*",
         "@user/data-state": "workspace:*"
diff --git a/packages-user/client-modules/src/client.ts b/packages-user/client-modules/src/client.ts
index 6311bd9..ab97dc0 100644
--- a/packages-user/client-modules/src/client.ts
+++ b/packages-user/client-modules/src/client.ts
@@ -10,7 +10,7 @@ import {
 } from '@motajs/audio';
 import { IRenderTreeRoot, MotaRenderer } from '@motajs/render';
 import {
-    IMaterialManager,
+    ITextureManager,
     IAutotileProcessor,
     MaterialManager,
     AutotileProcessor,
@@ -47,7 +47,7 @@ export class ClientCore extends CoreState implements IClientCore {
     readonly save: ISaveSystem;
 
     // Layer 5 渲染顶层
-    readonly materials: IMaterialManager;
+    readonly materials: ITextureManager;
     readonly autotile: IAutotileProcessor;
 
     readonly rafExcitation: IExcitation<number>;
diff --git a/packages-user/client-modules/src/fallback/load.ts b/packages-user/client-modules/src/fallback/load.ts
index 0e954f3..37a74bb 100644
--- a/packages-user/client-modules/src/fallback/load.ts
+++ b/packages-user/client-modules/src/fallback/load.ts
@@ -1,7 +1,7 @@
 import { ITexture } from '@motajs/render';
 import {
     IBlockIdentifier,
-    IMaterialManager,
+    ITextureManager,
     IIndexedIdentifier
 } from '@user/client-base';
 import { isNil } from 'lodash-es';
@@ -50,7 +50,7 @@ function addAutotile(set: Set<number>, map?: readonly (readonly number[])[]) {
 /**
  * 兼容旧版加载
  */
-export function fallbackLoad(materials: IMaterialManager) {
+export function fallbackLoad(materials: ITextureManager) {
     // 基本素材
     const icons = core.icons.icons;
     const images = core.material.images;
diff --git a/packages-user/client-modules/src/render/map/moving.ts b/packages-user/client-modules/src/render/map/moving.ts
index ea464cb..a61aa95 100644
--- a/packages-user/client-modules/src/render/map/moving.ts
+++ b/packages-user/client-modules/src/render/map/moving.ts
@@ -1,13 +1,13 @@
 import { linear, TimingFn } from 'mutate-animate';
 import { IMapRenderer, IMapVertexGenerator, IMovingBlock } from './types';
-import { IMaterialFramedData, IMaterialManager } from '@user/client-base';
+import { IMaterialFramedData, ITextureManager } from '@user/client-base';
 import { logger } from '@motajs/common';
 import { IMapLayer } from '@user/data-base';
 import { DynamicBlockStatus } from './status';
 
 export interface IMovingRenderer {
     /** 素材管理器 */
-    readonly manager: IMaterialManager;
+    readonly manager: ITextureManager;
     /** 顶点数组生成器 */
     readonly vertex: IMapVertexGenerator;
 
diff --git a/packages-user/client-modules/src/render/map/renderer.ts b/packages-user/client-modules/src/render/map/renderer.ts
index 486c83f..5850edf 100644
--- a/packages-user/client-modules/src/render/map/renderer.ts
+++ b/packages-user/client-modules/src/render/map/renderer.ts
@@ -10,7 +10,7 @@ import {
     BlockCls,
     IAutotileProcessor,
     IMaterialFramedData,
-    IMaterialManager,
+    ITextureManager,
     ITrackedAssetData
 } from '@user/client-base';
 import {
@@ -214,7 +214,7 @@ export class MapRenderer
      * 创建地图渲染器
      * @param manager 素材管理器
      */
-    constructor(readonly manager: IMaterialManager) {
+    constructor(readonly manager: ITextureManager) {
         this.movingIndexPool.push(
             ...Array.from({ length: this.movingCount }, (_, i) => i).reverse()
         );
diff --git a/packages-user/client-modules/src/render/map/types.ts b/packages-user/client-modules/src/render/map/types.ts
index 4d2486b..cab5924 100644
--- a/packages-user/client-modules/src/render/map/types.ts
+++ b/packages-user/client-modules/src/render/map/types.ts
@@ -7,7 +7,7 @@ import {
 import {
     IAutotileProcessor,
     IMaterialFramedData,
-    IMaterialManager,
+    ITextureManager,
     ITrackedAssetData
 } from '@user/client-base';
 import { IGameMap, IMapLayer } from '@user/data-base';
@@ -326,7 +326,7 @@ export interface IMapRenderResult {
 
 export interface IMapRenderer {
     /** 地图渲染器使用的资源管理器 */
-    readonly manager: IMaterialManager;
+    readonly manager: ITextureManager;
     /** 画布渲染上下文 */
     readonly gl: WebGL2RenderingContext;
 
diff --git a/packages-user/client-modules/src/types.ts b/packages-user/client-modules/src/types.ts
index 01c53e9..1a910ac 100644
--- a/packages-user/client-modules/src/types.ts
+++ b/packages-user/client-modules/src/types.ts
@@ -1,18 +1,12 @@
+import { IClientSystem } from '@user/client-system';
 import { IMapExtensionManager, IMapRenderer } from './render/map';
-import { IClientBase } from '@user/client-base';
-import { IExcitation, IExcitationDivider } from '@motajs/animate';
 
 export interface IClientCoreConfig {
     /** 渲染端数据配置文件路径，相对于 `src/content` */
     readonly clientURL: string;
 }
 
-export interface IClientCore extends IClientBase {
-    /** 用于渲染系统的 Raf 激励源 */
-    readonly rafExcitation: IExcitation<number>;
-    /** 用于渲染系统的激励源分频器 */
-    readonly excitationDivider: IExcitationDivider<number>;
-
+export interface IClientCore extends IClientSystem {
     /** 主地图渲染器，主要用于渲染游戏画面中的地图 */
     readonly mainMapRenderer: IMapRenderer;
     /** 副地图渲染器，主要用于渲染缩略图、浏览地图等内容 */
diff --git a/packages-user/client-system/package.json b/packages-user/client-system/package.json
new file mode 100644
index 0000000..d2258bf
--- /dev/null
+++ b/packages-user/client-system/package.json
@@ -0,0 +1,6 @@
+{
+    "name": "@user/client-system",
+    "dependencies": {
+        "@user/client-base": "workspace:*"
+    }
+}
diff --git a/packages-user/client-system/src/index.ts b/packages-user/client-system/src/index.ts
new file mode 100644
index 0000000..fcb073f
--- /dev/null
+++ b/packages-user/client-system/src/index.ts
@@ -0,0 +1 @@
+export * from './types';
diff --git a/packages-user/client-system/src/types.ts b/packages-user/client-system/src/types.ts
new file mode 100644
index 0000000..ac1297e
--- /dev/null
+++ b/packages-user/client-system/src/types.ts
@@ -0,0 +1,8 @@
+import { IClientBase } from '@user/client-base';
+
+export interface IClientSystem extends IClientBase {}
+
+export interface IClientSystemExtended {
+    /** 当前对象的渲染端系统层对象（Layer 5 对象） */
+    readonly state: IClientSystem;
+}
diff --git a/packages-user/data-state/src/types.ts b/packages-user/data-state/src/types.ts
index f38993c..c167a10 100644
--- a/packages-user/data-state/src/types.ts
+++ b/packages-user/data-state/src/types.ts
@@ -4,8 +4,6 @@ import { IStateSystem } from '@user/data-system';
 import { ISaveableContent } from '@user/data-common';
 import { IMotaDataLoader } from './loader/types';
 
-//#region 数据端主对象
-
 export interface ICoreStateConfig {
     /**
      * 加载启动器，用于适配不同加载环境。
@@ -44,4 +42,7 @@ export interface ICoreState
     ): void;
 }
 
-//#endregion
+export interface ICoreStateExtended {
+    /** 当前对象对应的数据层主对象（Layer 3 对象） */
+    readonly state: ICoreState;
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 949d480..7cb9a6e 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -428,6 +428,12 @@ importers:
       '@motajs/types':
         specifier: workspace:*
         version: link:../../packages/types
+      '@user/client-base':
+        specifier: workspace:*
+        version: link:../client-base
+      '@user/client-system':
+        specifier: workspace:*
+        version: link:../client-system
       '@user/data-base':
         specifier: workspace:*
         version: link:../data-base
@@ -438,6 +444,12 @@ importers:
         specifier: workspace:*
         version: link:../data-state
 
+  packages-user/client-system:
+    dependencies:
+      '@user/client-base':
+        specifier: workspace:*
+        version: link:../client-base
+
   packages-user/data-base:
     dependencies:
       '@motajs/common':