@eva/plugin-renderer-tilemap 2.1.0-beta.5 → 2.1.0-beta.6

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

@@ -1,5 +1,6 @@
 import { Component } from '@eva/eva.js';
 import { ComponentChanged } from '@eva/eva.js';
+import { Container } from 'pixi.js';
 import { ContainerManager } from '@eva/plugin-renderer';
 import { GameObject } from '@eva/eva.js';
 import { Renderer } from '@eva/plugin-renderer';
@@ -7,15 +8,633 @@ import { RendererManager } from '@eva/plugin-renderer';
 import { RendererSystem } from '@eva/plugin-renderer';
 
 /**
- * Phaser-style Static Tilemap 渲染组件(MVP)。
+ * Adapter:把 host 端 installPerfProbes 的 API 适配到 PerfProbeRegistry。
  *
- * 行为:
- * 1. 从 `tileset` 资源加载一张 spritesheet 纹理;
- * 2. 每个 layer 对应一个 PixiJS Container;
- * 3. layer 内每个非零 tile 都创建一个 Sprite,texture 由原 tileset 切片得到;
- * 4. tile 在 layer Container 内的位置:`(col * tileW + offsetX, row * tileH + offsetY)`。
+ * ADR-0013 的 installPerfProbes 暴露 `game.perfProbes?.{begin,end,count,gauge}` 等
+ * 命名空间。这里只做转发,host 决定具体接入哪个版本。
+ */
+export declare function adaptGamePerfProbes(game: {
+    perfProbes?: Partial<PerfProbeRegistry>;
+}): PerfProbeRegistry | null;
+
+/**
+ * Status flag — true once ADR-0019 lands and this host stop-gap can be removed.
+ *
+ * Hosts can branch on this to switch from the child-GameObject workaround to a
+ * direct registry handshake. Until then, importing this module signals "I am
+ * using the pre-ADR-0019 path".
+ */
+export declare const ADR_0019_NATIVE_REGISTRY_AVAILABLE = false;
+
+export declare interface AdvanceResult {
+    /** key = `${slot},${col},${row}` → 当前帧 atlas (col,row) */
+    currentFrames: Map<string, {
+        col: number;
+        row: number;
+    }>;
+    /** key set:相比上次 advance() 改变了 currentFrame 的 tiles。 */
+    dirtyKeys: Set<string>;
+}
+
+declare interface AtlasTileRaw {
+    atlasCoords: {
+        col: number;
+        row: number;
+    };
+    size?: {
+        width: number;
+        height: number;
+    };
+    alternatives: Array<{
+        altId: number;
+        modulate?: string;
+        zIndex?: number;
+        probability?: number;
+        [extra: string]: unknown;
+    }>;
+}
+
+export declare interface AutotileCandidate {
+    sourceSlot: number;
+    col: number;
+    row: number;
+    altIdx: number;
+    probability: number;
+    terrain: number;
+}
+
+export declare interface BodyDefinition {
+    id: string;
+    /** 局部顶点 — Matter.js 会用 fromVertices 构建 polygon body。 */
+    vertices: BodyVec2[];
+    /** body 中心(world coords)。 */
+    centerX: number;
+    centerY: number;
+    isStatic: boolean;
+    friction?: number;
+    restitution?: number;
+    oneWay?: boolean;
+    categoryFilter?: number;
+    maskFilter?: number;
+    metadata?: Record<string, unknown>;
+}
+
+export declare type BodySourceBuilder = (ctx: BodySourceContext) => BodyDefinition[];
+
+export declare interface BodySourceContext {
+    worldX: number;
+    worldY: number;
+}
+
+declare class BodySourceRegistryImpl {
+    private builders;
+    register(name: string, builder: BodySourceBuilder): void;
+    unregister(name: string): void;
+    has(name: string): boolean;
+    build(name: string, ctx: BodySourceContext): BodyDefinition[] | null;
+    listRegisteredNames(): string[];
+    clear(): void;
+}
+
+/**
+ * Body source registry shim(G1)。
+ *
+ * 真实 plugin-matterjs `registerBodySource` API 落地需要 ADR-0019 评审 + BREAKING
+ * change。这里先 ship 一个完全相同的抽象层,plugin-renderer-tilemap 内部用它建
+ * TileMapStaticBody body 集合。host 在初始化时把这个 registry 喂给 plugin-matterjs
+ * (或直接消费它建 Matter.Composite)。
+ *
+ * 当 ADR-0019 落地后,只需要把这里的 import 切到 @eva/plugin-matterjs/lib/body-source。
+ */
+declare interface BodyVec2 {
+    x: number;
+    y: number;
+}
+
+/**
+ * Build geometry for a chunk。chunkX/Y 是 chunk 在世界坐标的左上(已含 mapOrigin)。
+ */
+export declare function buildChunkGeometry(args: {
+    cells: Int32Array;
+    chunkWorldX: number;
+    chunkWorldY: number;
+    cellWidth: number;
+    cellHeight: number;
+    atlasInfo: ChunkGeometryAtlasInfo;
+}): ChunkGeometryResult;
+
+/**
+ * 创建一个 chunk 的 Mesh-path render container。
+ *
+ * 当前实现:返回 Container stub。Cycle 2 接入真实 PIXI.Mesh + 自定义 shader 时
+ * 替换内部实现即可,调用方接口不变(返回 Container,由 ChunkRenderer 加到 stage)。
+ *
+ * 接口稳定保证:
+ *   - 返回 Container 必须有 children 数组(Container 默认即有)
+ *   - 返回的 Container 在 destroy() 时正确释放纹理
+ */
+export declare function buildChunkMesh(_config: ChunkMeshConfig): Container;
+
+/**
+ * Build BodyDefinition[] for an entire TileMap layer。
+ *
+ * 每 cell 引用 TileSet 中对应 tile 的 physics polygons:
+ *   - 在 cache 里查 cached convex parts(load 时已 decompose)
+ *   - 没缓存就 decomposePolygon stub(当前 polygon=convex 直接返回)
+ *   - translate 到 cell world 位置
+ */
+export declare function buildTileMapStaticBodies(input: TileMapStaticBodyInput, ctx: BodySourceContext): BodyDefinition[];
+
+/**
+ * Build BodyDefinition[] for a TileMap entity and group by physics layer.
+ *
+ * The host is expected to call this after `system.handleAdd` resolves and the
+ * record has its `loadedTileset`. The host passes:
+ *   - chunksByKey from `decodeChunk(layer.cellData.chunks[key])`
+ *   - physicsByCellKey derived from `loadedTileset.raw.sources[i].tiles[j].alternatives[k].physics`
+ *
+ * This keeps the runtime plugin agnostic of how the host actually registers bodies
+ * with Matter (child GameObject + Physics component vs. direct Matter.Composite.add).
+ */
+export declare function buildTileMapStaticBodyDefinitions(input: TileMapStaticBodyInput, ctx: BodySourceContext, 
+/**
+ * T-L3 (Phase L):optional probe registry。当 host 注入时,本函数会:
+ *   - PHYSICS_REBAKE_MS:wrap 整个 buildTileMapStaticBodies 调用计时
+ *   - BODIES_TOTAL:emit gauge,反映当前生成的 body 总数
+ *   - BODIES_CREATED:counter+totalBodyCount,统计累计 created
+ * 不注入时 silent no-op,保持与现有 caller 行为兼容。
+ * BODIES_DESTROYED 暂未 emit(无清晰 destroy point),Cycle 2 再补。
+ */
+probes?: PerfProbeRegistry): TileMapStaticBodyHostBuildResult;
+
+export declare interface CachedDecomposition {
+    parts: ConvexPart[];
+    /** 物理材质参数,Phase 3 时由 plugin-matterjs 消费。 */
+    friction?: number;
+    restitution?: number;
+    oneWay?: boolean;
+}
+
+export declare function cacheKeyOf(k: DecompositionCacheKey): string;
+
+export declare function cacheKeyOfNum(slot: number, col: number, row: number, altIdx: number): number;
+
+declare interface CellRecord {
+    sourceSlot: number;
+    col: number;
+    row: number;
+    altIdx: number;
+    flipH: boolean;
+    flipV: boolean;
+    transpose: boolean;
+}
+
+/**
+ * 与 libs/dsl/src/editor/chunk-codec.ts 同形的解码 helper。
+ * 在 plugin 内复制一份是为了避免 @eva/* 反向依赖 @ali/eva-dsl 或本仓 libs/dsl。
+ *
+ * 这里只需要解码 + 拆 cell;编码留给 DSL 编辑层。
+ */
+export declare const CHUNK_SIZE = 16;
+
+/**
+ * Chunked cell data。与 libs/dsl 的 ChunkedCellData 同形,但为避免反向依赖,
+ * 在这里独立声明接口(结构兼容 JSON shape)。
+ *
+ * Cell encoding (1 int32 per cell):
+ *   bits 0..7    sourceSlot     (1..255,0 = 空)
+ *   bits 8..15   col
+ *   bits 16..23  row
+ *   bits 24..28  altIdx
+ *   bit  29      flipH
+ *   bit  30      flipV
+ *   bit  31      transpose
+ */
+export declare interface ChunkedCellData {
+    kind: 'chunked';
+    chunkSize: 16;
+    stride: 1;
+    chunks: Record<string, {
+        blob: string;
+        nonEmpty: number;
+    }>;
+}
+
+/**
+ * Build packed vertex/index buffers for a chunk mesh(G3)。
+ *
+ * 输入:Int32Array(256 packed cells)+ atlas region info。
+ * 输出:Float32Array (vertex data) + Uint16Array (indices)。
+ *
+ * 每非空 cell 4 vertices × 8 floats(2 pos + 2 uv + 4 flags) = 32 floats = 128B。
+ * 6 indices/quad × 2B = 12B index。
+ */
+export declare interface ChunkGeometryAtlasInfo {
+    regionWidth: number;
+    regionHeight: number;
+    textureWidth: number;
+    textureHeight: number;
+    margins: {
+        x: number;
+        y: number;
+    };
+    separation: {
+        x: number;
+        y: number;
+    };
+}
+
+export declare interface ChunkGeometryResult {
+    vertexData: Float32Array;
+    indices: Uint16Array;
+    quadCount: number;
+}
+
+export declare interface ChunkMeshConfig {
+    chunkKey: string;
+    chunkX: number;
+    chunkY: number;
+    cellWidth: number;
+    cellHeight: number;
+    /** Atlas 纹理 — Mesh shader 通过 uTexture 采样。 */
+    atlas: unknown;
+    /** Cell record array (256 ints) — 用于 vertex attribute upload。 */
+    cells: Int32Array;
+    /** Tile region width / height in atlas (regionSize)。 */
+    regionWidth: number;
+    regionHeight: number;
+    /** atlas margins / separation,用于 UV 计算。 */
+    margins?: {
+        x: number;
+        y: number;
+    };
+    separation?: {
+        x: number;
+        y: number;
+    };
+}
+
+export declare interface ChunkRenderStrategyContext {
+    nonEmptyCellsInChunk: number;
+    atlasesInChunk: number;
+    totalChunksVisible: number;
+    preference?: ChunkRenderStrategyKind;
+}
+
+/**
+ * Chunk render strategy(Phase 4).
+ *
+ * 当前 system.ts 直接走 sprite-entity 路径(每非空 cell 一个 PIXI.Sprite),
+ * 简单可靠。Phase 4 引入 strategy 接口为后续 Mesh 路径预留位置:
+ *   - sprite:Phase 1 MVP 路径,适合 < 4096 个 cell / chunk 数 < 30 的场景
+ *   - mesh: 单 chunk 一次 draw call,适合 200×200 60% 填充等高密度
+ *   - auto: 按 chunk 内非空 cell 数与 atlas 数动态选择
+ *
+ * 这里只 ship strategy interface + sprite 实现 + auto-pick 阈值;实际 PIXI.Mesh
+ * shader 在下一轮 cycle 落地(见 ADR-0018 §11 未决问题 2)。
+ */
+export declare type ChunkRenderStrategyKind = 'sprite' | 'mesh' | 'auto';
+
+export declare interface CompiledTileAnimation {
+    sourceSlot: number;
+    col: number;
+    row: number;
+    frames: TileAnimationFrame[];
+    totalDurationMs: number;
+    phase: 'sync' | 'randomStart';
+    phaseOffsetMs: number;
+}
+
+/**
+ * 给定 diff 结果 + 文档 chunks(`chunkKey → Int32Array`),返回需要 rebuild 的 chunk key set。
+ *
+ * 算法:遍历所有 chunks,对每个非空 cell,如果它引用的 atlas (sourceSlot, col, row) 在 changed
+ * /removed/added tile set 里,标记该 chunk dirty。
+ */
+export declare function computeAffectedChunks(chunks: Record<string, Int32Array>, sourceIdBySlot: Map<number, string>, diff: TilesetChunkRebuildDiff): Set<string>;
+
+/**
+ * DecompositionCache(C1,关联 ADR-0019)。
+ *
+ * TileSet 上每 alt tile 可能有任意 polygon collision shape。Matter.js 要求 convex,
+ * concave 需 poly-decomp。decompose 是 O(n²),不能每 paint stroke 重做。
+ *
+ * 这里在 TileSet load 时把每 alt tile 的 polygon list 一次性 decompose 成 convex parts,
+ * 后续 stroke 只走 translate;decompose 结果按 (sourceSlot, col, row, altIdx, layerId) key 缓存。
+ *
+ * 当前 cycle:cache 数据结构 + key 生成 + LRU eviction skeleton 实现完毕,真 poly-decomp
+ * 在 Phase 3 落地时接入 npm `poly-decomp` 包。
+ */
+export declare interface ConvexPart {
+    /** 顶点列表(局部坐标,相对 tile 中心或左上)。 */
+    vertices: Array<{
+        x: number;
+        y: number;
+    }>;
+}
+
+/** 创建一个内存收集器(测试用)。 */
+export declare function createInMemoryProbeRegistry(): PerfProbeRegistry & {
+    timings: Map<string, number[]>;
+    counts: Map<string, number>;
+    gauges: Map<string, number>;
+};
+
+export declare function decodeChunk(blob: {
+    blob: string;
+    nonEmpty: number;
+}): Int32Array;
+
+/**
+ * 暂时占位的 polygon → convex parts 函数。
+ * Phase 3 落地 npm `poly-decomp` 时替换实现;当前假设输入已 convex,
+ * 输入 concave polygon(L/T/U/凹槽)会 throw,防止静默产出错误 Matter body。
+ *
+ * Host 应在 paint 前用 isConvex 做 pre-check,把 concave 提示给用户,避免触发 throw。
+ */
+export declare function decomposePolygon(polygon: Array<{
+    x: number;
+    y: number;
+}>): ConvexPart[];
+
+export declare class DecompositionCache {
+    private readonly maxEntries;
+    private cache;
+    private accessOrder;
+    private accessCounter;
+    constructor(maxEntries?: number);
+    get(key: DecompositionCacheKey): CachedDecomposition | undefined;
+    set(key: DecompositionCacheKey, value: CachedDecomposition): void;
+    has(key: DecompositionCacheKey): boolean;
+    clear(): void;
+    get size(): number;
+    private evictLRU;
+}
+
+export declare interface DecompositionCacheKey {
+    sourceSlot: number;
+    col: number;
+    row: number;
+    altIdx: number;
+    layerId: string;
+}
+
+/**
+ * @deprecated Use `diffTilesetForChunkRebuild`. Alias kept for transitional
+ * compatibility — the name collided with `@ali/eva-dsl`'s `diffTilesetDocuments`
+ * (document-level detailed diff for host UX), which has different semantics.
+ */
+export declare const diffTilesetDocuments: typeof diffTilesetForChunkRebuild;
+
+/**
+ * 计算两个 TilesetDocumentRaw 之间的 source/tile-level coarse diff,供
+ * `computeAffectedChunks` 决定哪些 chunk 要 rebuild。
+ *
+ * 不要与 `@ali/eva-dsl` 的 `diffTilesetDocuments` 混淆 — 后者是 document-level
+ * detailed diff(per alternative / animation / customData / physics / terrain),
+ * 用于 host UX 显示,不是 chunk-rebuild 决策。
+ */
+export declare function diffTilesetForChunkRebuild(prev: TilesetDocumentRaw, next: TilesetDocumentRaw): TilesetChunkRebuildDiff;
+
+/**
+ * 估算单 chunk Mesh path 占用 GPU memory(单位 KB)。
+ * 用于 perf probes,Mesh path 上线后 budget 监控参考。
+ */
+export declare function estimateChunkMeshMemoryKB(config: ChunkMeshConfig): number;
+
+/**
+ * 估算单个 chunk 在 sprite 路径下的额外 PIXI 节点开销(用于 perf-probe)。
+ */
+export declare function estimateSpriteNodes(nonEmptyCellsInChunk: number): number;
+
+/**
+ * 把 sceneCollection source 展开成 prefab ref 数组。
+ */
+export declare function expandSceneCollectionSource(src: TilesetSourceRaw): SceneCollectionPrefabRef[];
+
+/**
+ * Extract `physicsByCellKey` Map from a LoadedTileset's raw atlas tile data.
+ *
+ * Each tile alternative may carry `physics: Array<{ layerId, polygons, oneWay, friction, restitution }>`.
+ * The returned Map is keyed by `${slot},${col},${row},${altIdx}` matching the cell-packed
+ * id format used by `buildTileMapStaticBodies`.
+ */
+export declare function extractPhysicsByCellKey(tilesetRaw: {
+    sources: Array<{
+        kind: string;
+        tiles?: Array<{
+            atlasCoords: {
+                col: number;
+                row: number;
+            };
+            alternatives: Array<{
+                altId: number;
+                physics?: Array<{
+                    layerId: string;
+                    polygons: Array<{
+                        points: Array<{
+                            x: number;
+                            y: number;
+                        }>;
+                        origin?: "center" | "topLeft";
+                    }>;
+                    oneWay?: boolean;
+                    friction?: number;
+                    restitution?: number;
+                }>;
+            }>;
+        }>;
+    }>;
+}): TileMapStaticBodyInput["physicsByCellKey"];
+
+/**
+ * Coverage 计算 — Phase B 门禁要求 budgetCoverage ≥ 0.95。
+ * 这里返回当前 hot-path 涉及的 probe 名字集合,host 用它对比 installPerfProbes 实际
+ * 注册的 probe set。
+ */
+export declare function getRequiredTilemapProbes(): string[];
+
+export declare function isEmptyCellValue(packed: number): boolean;
+
+/** 返回 true 表示当前环境支持 Mesh path(需要 WebGL2 + Program shader)。 */
+export declare function isMeshPathAvailable(): boolean;
+
+/** 运行时解析后的 frozen TileSet。 */
+export declare interface LoadedTileset {
+    raw: TilesetDocumentRaw;
+    /** sourceSlot 索引(1-based):slot 0 = empty,slot 1 = sources[0]。 */
+    sourcesBySlot: TilesetSourceRaw[];
+    /** id → slot,patch 寻址用。 */
+    slotByIdMap: Map<string, number>;
+    tileWidth: number;
+    tileHeight: number;
+}
+
+export declare function makeLoadedTileset(raw: TilesetDocumentRaw): LoadedTileset;
+
+export declare const MAX_TERRAIN_ID = 14;
+
+/**
+ * Autotile peering-bit index (Phase 2).
+ *
+ * 在 TileSet load 时构建,把每个 alt tile 的 peering bits 编进 hash key
+ * 实现 O(1) 邻居匹配。
  *
- * 不支持(Phase 2 视情况增加):tile flipping、动态修改 API、iso/hex、physics 碰撞、camera。
+ * 数据模型:
+ * - 一个 terrainSet 有最多 8 个方向(Godot corners+sides),每个方向上当前
+ *   邻居的 terrain id 取值 0..255。
+ * - 把 8 个方向打包成一个 BigInt 作 exact-match key:每 byte 一个方向。
+ * - 通配 (`undefined` neighbor) 用 0xff 哨兵表示;查询时构造 actual neighborhood
+ *   也用 0xff 表示"无邻居 / 空 cell"。
+ * - exact 命中优先;否则在 wildcard 桶里按 Hamming 距离打分,取最小者(同分则
+ *   按 probability 加权随机 - 注意此处仅返回候选,不做 RNG)。
+ *
+ * 这里只暴露纯函数 + 数据结构,RNG/decision 留给 AutotileCommand 调用方。
+ */
+export declare const NEIGHBOR_DIRECTIONS: readonly ["topLeft", "top", "topRight", "right", "bottomRight", "bottom", "bottomLeft", "left"];
+
+export declare type NeighborDirection = (typeof NEIGHBOR_DIRECTIONS)[number];
+
+/**
+ * 4-bit-per-direction × 8 directions = 32-bit number 作 hash key。
+ * terrain id 范围 0..14;15 (0xf) 作 NO_NEIGHBOR / wildcard 哨兵。
+ * v1 限制最多 15 个 terrain per terrain set,足够 Godot 47-tile Wang 集。
+ */
+export declare const NO_NEIGHBOR = 15;
+
+/**
+ * Build the index from a TileSet's terrainSet candidates.
+ *
+ * `candidates` is the flat list of all (sourceSlot, col, row, altIdx) belonging
+ * to the given terrainSet, each with optional peeringBits + probability.
+ */
+export declare class PeeringBitIndex {
+    readonly terrainSetIndex: number;
+    private exact;
+    private wildcards;
+    constructor(terrainSetIndex: number);
+    add(candidate: AutotileCandidate, bits: PeeringBitsRecord | undefined): void;
+    /**
+     * Match an `actual` neighborhood:8 byte values, NO_NEIGHBOR for "empty".
+     *
+     * Returns the set of best-matching candidates (Hamming distance 0 = exact).
+     * If no candidate matches at any distance, returns empty list.
+     */
+    match(actual: number[]): PeeringBitMatchResult;
+    get exactBucketCount(): number;
+    get wildcardCount(): number;
+}
+
+export declare interface PeeringBitMatchResult {
+    candidates: AutotileCandidate[];
+    exactMatch: boolean;
+    bestHammingDistance: number;
+}
+
+export declare interface PeeringBitsRecord {
+    [direction: string]: number;
+}
+
+/**
+ * Tilemap performance probes(Sprint C B3,关联 ADR-0013)。
+ *
+ * 提供 11 个 probe(11 计时器 / 计数器),host 可通过 installTilemapPerfProbes(game)
+ * 把它们注册到 ADR-0013 的 installPerfProbes 命令式 API 中。
+ *
+ * 当前不直接依赖 ADR-0013 的 perf 包(避免循环依赖),改为暴露 PerfProbeRegistry
+ * 接口,host 注入。这样:
+ *   - Phase B 门禁:budgetCoverage 通过这 11 个 probe 计入
+ *   - 测试场景:host 可注入 in-memory 收集器 verify metrics
+ */
+export declare interface PerfProbeRegistry {
+    /** 计时 probe — 调 begin → 操作 → end,记录耗时。 */
+    beginTiming(name: string): void;
+    endTiming(name: string): void;
+    /** 计数 probe — 累加。 */
+    count(name: string, delta?: number): void;
+    /** 距离值 probe — gauge,记录当前瞬时值。 */
+    gauge(name: string, value: number): void;
+    /** 分布 probe — histogram(可选)。 */
+    histogram?(name: string, value: number): void;
+}
+
+/**
+ * Probability-weighted picker — deterministic when seed is provided.
+ */
+export declare function pickAutotileCandidate(candidates: AutotileCandidate[], rng: () => number): AutotileCandidate | null;
+
+/**
+ * 给定 packed cell + source 列表,查这个 cell 对应的 prefab name(如果是 scene-collection
+ * source);atlas source 返回 null。
+ */
+export declare function resolveCellPrefabName(packed: number, sourcesBySlot: TilesetSourceRaw[]): string | null;
+
+/**
+ * 决定单个 chunk 走哪条渲染路径。
+ *
+ * 阈值来源于 ADR-0018 §10 风险登记册(Phase 4 P2-7 改造):
+ * - 单 chunk 非空 cell 数 >= 192 (75%) 且单 atlas → mesh
+ * - 多 atlas → sprite(等 texture-array 支持后再切 mesh)
+ * - 否则 sprite 简单稳定
+ */
+export declare function resolveChunkRenderStrategy(ctx: ChunkRenderStrategyContext): ChunkRenderStrategyKind;
+
+export declare interface SceneCollectionPrefabRef {
+    sourceId: string;
+    prefabName: string;
+    /**
+     * 在 source 内的索引(等价 atlas 的 atlasCoords;UI 上以 0-based 列出)。
+     */
+    index: number;
+}
+
+export declare const TILE_FRAG_SHADER = "#version 300 es\nprecision highp float;\n\nin vec2 vTexCoord;\nout vec4 fragColor;\n\nuniform sampler2D uTexture;\nuniform vec4 uModulate;\n\nvoid main() {\n  vec4 sampled = texture(uTexture, vTexCoord);\n  fragColor = sampled * uModulate;\n  if (fragColor.a < 0.01) discard;\n}\n";
+
+export declare const TILE_SHADER_SOURCES: TileShaderSources;
+
+/**
+ * Tile mesh shader 源码(G3)。
+ *
+ * PIXI v8 用 ProgramSource + Geometry,程序员手工写 GLSL 即可。这里 vert/frag
+ * 走 packed vertex attribute,flip/transpose 在 vertex 阶段通过 mat2 完成。
+ *
+ * Attribute 布局(每 vertex 32 bytes):
+ *   aPosition vec2 (8B)  cell 左上 + 局部偏移
+ *   aTexCoord vec2 (8B)  atlas UV 0..1
+ *   aFlags    vec4 (16B) [flipH, flipV, transpose, animPhase]
+ */
+export declare const TILE_VERT_SHADER = "#version 300 es\nprecision highp float;\n\nin vec2 aPosition;\nin vec2 aTexCoord;\nin vec4 aFlags;\n\nuniform mat3 uProjectionMatrix;\nuniform mat3 uWorldTransformMatrix;\n\nout vec2 vTexCoord;\n\nvoid main() {\n  vec3 worldPos = uWorldTransformMatrix * vec3(aPosition, 1.0);\n  gl_Position = vec4((uProjectionMatrix * worldPos).xy, 0.0, 1.0);\n\n  vec2 uv = aTexCoord;\n  if (aFlags.x > 0.5) uv.x = 1.0 - uv.x;\n  if (aFlags.y > 0.5) uv.y = 1.0 - uv.y;\n  if (aFlags.z > 0.5) { float t = uv.x; uv.x = uv.y; uv.y = t; }\n  vTexCoord = uv;\n}\n";
+
+export declare class TileAnimationDriver {
+    private animations;
+    private lastFrameIdxByKey;
+    loadFromTileset(raw: TilesetDocumentRaw): void;
+    get animationCount(): number;
+    /** True when (slot,col,row) is the source tile of an animation in this driver. */
+    isAnimatedSource(slot: number, col: number, row: number): boolean;
+    advance(nowMs: number): AdvanceResult;
+    reset(): void;
+}
+
+export declare interface TileAnimationFrame {
+    col: number;
+    row: number;
+    durationMs: number;
+}
+
+export declare interface TileAnimationKey {
+    sourceSlot: number;
+    col: number;
+    row: number;
+}
+
+/**
+ * Tilemap 渲染组件。
+ *
+ * v1 (Phaser-style, 静态): 通过 `tileset` + `layers[].data[][]` 渲染。
+ * v2 (Godot-style, chunked): 通过 `tilemapRef` + `layersV2[].cellData.chunks` 渲染。
+ *
+ * System 通过有无 `tilemapRef` 判断走哪条路径。两条路径不共存于同一实例。
  */
 export declare class Tilemap extends Component<TilemapParams> {
     static componentName: string;
@@ -28,12 +647,93 @@ export declare class Tilemap extends Component<TilemapParams> {
     renderTileWidth?: number;
     renderTileHeight?: number;
     layers: TilemapLayer[];
+    tilemapRef: string;
+    mapOrigin?: {
+        x: number;
+        y: number;
+    };
+    cellSize?: {
+        width: number;
+        height: number;
+    };
+    layersV2?: TileMapLayerV2[];
+    collisionEnabled?: boolean;
+    navigationEnabled?: boolean;
+    animationEnabled?: boolean;
+    renderStrategy?: 'sprite' | 'mesh' | 'auto';
     init(obj?: TilemapParams): void;
 }
 
+export declare const TILEMAP_BODY_SOURCE_REGISTRY: BodySourceRegistryImpl;
+
+/** Probe 名称常量,与 ADR-0018 §4.6 表对齐。 */
+export declare const TILEMAP_PROBE_NAMES: {
+    readonly DIRTY_REBUILD_MS: "tilemap.dirtyRebuild.ms";
+    readonly CULL_CHECK_MS: "tilemap.cullCheck.ms";
+    readonly ANIM_TICK_MS: "tilemap.animTick.ms";
+    readonly DRAWCALLS_COUNT: "tilemap.drawcalls.count";
+    readonly DRAWCALLS_BY_ATLAS: "tilemap.drawcalls.byAtlas";
+    readonly PHYSICS_REBAKE_MS: "tilemap.physicsRebake.ms";
+    readonly GPU_UPLOAD_MS: "tilemap.gpuUpload.ms";
+    readonly GPU_UPLOAD_BYTES: "tilemap.gpuUpload.bytes";
+    readonly AUTOTILE_MS: "tilemap.autotile.ms";
+    readonly PATCH_APPLY_MS: "tilemap.patchApply.ms";
+    readonly DIRTY_PENDING: "tilemap.dirty.pending";
+    readonly DIRTY_FRAMES_BEHIND: "tilemap.dirty.framesBehind";
+    readonly BODIES_TOTAL: "tilemap.bodies.total";
+    readonly BODIES_CREATED: "tilemap.bodies.created";
+    readonly BODIES_DESTROYED: "tilemap.bodies.destroyed";
+    /**
+     * ChunkRenderStrategy dispatch counters(P1-3, ADR-0018 §Phase 4).
+     * 每构建一个 chunk emit 一次,分别记录 sprite / mesh / mesh-降级-sprite 的次数。
+     */
+    readonly STRATEGY_SPRITE_COUNT: "tilemap.strategy.sprite.count";
+    readonly STRATEGY_MESH_COUNT: "tilemap.strategy.mesh.count";
+    readonly STRATEGY_MESH_FALLBACK_COUNT: "tilemap.strategy.meshFallback.count";
+    /**
+     * SceneCollection cell skip counter(P1-4, ADR-0018 §H2).
+     * 当 TileMap chunk 内含 sceneCollection source 的 cell 时,runtime 暂时跳过(不渲染),
+     * 每跳过一次累加 1。配合每条 record 一次性 console.warn,提示需要 prefab placeholder 实现。
+     */
+    readonly SCENECOLLECTION_SKIPPED_COUNT: "tilemap.sceneCollection.skipped.count";
+    /**
+     * Viewport culling hits counter(C-2, ADR-0018 §Phase 4)。
+     * 每次 buildChunksForLayer 跳过一个 off-screen chunk 时累加 1。
+     * 当前 record-level `cullingBoundsHint` 由 host 注入(可选),未注入时该 probe 永远为 0。
+     * 真正的 camera-driven viewport 接入留下 cycle(参考 RendererSystem.application.renderer.view)。
+     */
+    readonly CULL_HITS_COUNT: "tilemap.cull.hits";
+    /**
+     * Mode-switch failure counter(T-L2, Phase L)。
+     * 当 handleChange 内部 v1↔v2 mode 切换时,新 mode 的 asset 加载失败导致旧 mode 已 teardown
+     * 又 build 不出来的情况:record.mode='unknown',probe 累加 1。host 看到 >0 表示 tilemap 资源
+     * 异常,需要诊断 tilemapRef/tileset 引用是否有效。
+     */
+    readonly MODE_SWITCH_FAILED_COUNT: "tilemap.modeSwitch.failed";
+    /**
+     * Animation tick error counter(T-N1, Phase N)。
+     *
+     * update() 内每帧 advance 每个 animation driver。某个 driver advance / 后续 sprite swap
+     * throw 时,本 probe +1 并 console.error 之,但不影响其他 entity 的 tick(try/catch 局部
+     * 包裹,外层 try/finally 确保 ANIM_TICK_MS endTiming 一定被调)。host 看到该 probe >0 表示
+     * tilemap 有 entity 的 animation pipeline 异常,需要诊断。
+     */
+    readonly ANIM_TICK_ERROR_COUNT: "tilemap.animTick.error.count";
+    /**
+     * WebGL context lost counter(T-N2, Phase N)。
+     *
+     * Eva runtime 监听 canvas 的 `webglcontextlost`,触发时本 probe +1,并把 record-level
+     * `contextLost = true` 暂停 tilemap update tick;`webglcontextrestored` 时清掉该标志。
+     * host 看到 >0 即知 WebGL 异常,通常需要在 restored 后 force re-add tilemap component
+     * 重新建几何。
+     */
+    readonly CONTEXT_LOST_COUNT: "tilemap.context.lost";
+};
+
 /**
  * 单个 Tilemap layer 的描述。
  *
+ * Phaser-style 静态 tilemap(v1 老路径):
  * - `data` 为二维数组,行优先(row-major):data[row][col]。
  * - tile id `0` 表示空格,不渲染;> 0 的 id 会按 `(id - 1)` 索引到 tileset 的第 N 个 tile。
  * - `offsetX/offsetY` 在 layer 级别整体偏移(等价 Phaser createLayer(... ,x,y))。
@@ -52,44 +752,331 @@ export declare interface TilemapLayer {
     tint?: number;
 }
 
+export declare interface TileMapLayerV2 {
+    id: string;
+    name?: string;
+    enabled?: boolean;
+    visible?: boolean;
+    locked?: boolean;
+    modulate?: string;
+    opacity?: number;
+    zIndex?: number;
+    yOrigin?: 'topLeft' | 'center';
+    ySort?: boolean;
+    ySortOriginPx?: number;
+    collisionEnabled?: boolean;
+    navigationEnabled?: boolean;
+    animationEnabled?: boolean;
+    cellData: ChunkedCellData;
+}
+
 export declare interface TilemapParams {
     /** Tileset 图像资源 key(对应 DSL assets 中的 image 资源)。 */
-    tileset: string;
+    tileset?: string;
     /** 单个 tile 在 tileset 中的宽度。 */
-    tileWidth: number;
+    tileWidth?: number;
     /** 单个 tile 在 tileset 中的高度。 */
-    tileHeight: number;
-    /**
-     * Tileset 横向有几列 tile。Tileset 图像总宽 ≥ tilesetColumns * tileWidth。
-     * 如果不传,会使用 tileset 图实际尺寸 / tileWidth 推断。
-     */
+    tileHeight?: number;
     tilesetColumns?: number;
-    /** Tileset 内部 tile 之间的间距,默认 0。 */
     tilesetSpacing?: number;
-    /** Tileset 内部 tile 与图像边缘的 margin,默认 0。 */
     tilesetMargin?: number;
-    /** 渲染时的 tile 显示宽度;不传则与 tileWidth 一致(用于切片放大)。 */
     renderTileWidth?: number;
-    /** 渲染时的 tile 显示高度。 */
     renderTileHeight?: number;
-    /** 多个 layer。 */
-    layers: TilemapLayer[];
+    layers?: TilemapLayer[];
+    /** 当存在时,System 走 chunked 路径,忽略 tileset/layers 老字段。 */
+    tilemapRef?: string;
+    mapOrigin?: {
+        x: number;
+        y: number;
+    };
+    /** 单 cell 像素;默认从 tileset 文档的 tileSize 派生。 */
+    cellSize?: {
+        width: number;
+        height: number;
+    };
+    layersV2?: TileMapLayerV2[];
+    collisionEnabled?: boolean;
+    navigationEnabled?: boolean;
+    animationEnabled?: boolean;
+    renderStrategy?: 'sprite' | 'mesh' | 'auto';
+}
+
+export declare interface TileMapStaticBodyHostBuildResult {
+    bodies: BodyDefinition[];
+    /** Per-cell body count summary for diagnostics + perf probe `tilemap.bodies.total` gauge. */
+    totalBodyCount: number;
+    /** Bodies grouped by layerId (from BodyDefinition.metadata.layerId). */
+    bodiesByLayerId: Map<string, BodyDefinition[]>;
+}
+
+export declare interface TileMapStaticBodyInput {
+    /** 已 hydrate 的 chunked cells:`chunkKey → Int32Array(256)`。 */
+    chunksByKey: Record<string, Int32Array>;
+    /** TileSet alt tile 的 physics 数据。 */
+    physicsByCellKey: Map<string, Array<{
+        layerId: string;
+        polygons: Array<{
+            points: Array<{
+                x: number;
+                y: number;
+            }>;
+            origin?: "center" | "topLeft";
+        }>;
+        oneWay?: boolean;
+        friction?: number;
+        restitution?: number;
+    }>>;
+    cellWidth: number;
+    cellHeight: number;
+    mapOriginX: number;
+    mapOriginY: number;
+    cache: DecompositionCache;
 }
 
 export declare class TilemapSystem extends Renderer {
     static systemName: string;
     name: string;
     private records;
+    /** Animation driver per Tilemap entity(只有 v2 路径有 animation,v1 不用)。 */
+    private animationDrivers;
+    /**
+     * Perf probe sink (ADR-0013 + ADR-0018 §4.6).
+     * Resolved from `game.perfProbes` in init(); null when host did not install probes —
+     * all helper methods become no-ops, no overhead in production builds without perf.
+     */
+    private probes;
+    /**
+     * T-N2 (Phase N):tab visibility / WebGL context loss state。
+     * - `isHidden`:document.visibilityState === 'hidden' 时为 true,update() early return
+     * - `contextLost`:webglcontextlost 事件触发为 true;webglcontextrestored 清回 false
+     * - listener 引用保留以便 destroy 时 detach(避免内存泄漏)
+     */
+    private isHidden;
+    private contextLost;
+    private visibilityListener?;
+    private contextLostListener?;
+    private contextRestoredListener?;
+    /** T-N2:已 install handlers 的 canvas 引用,destroy 时 detach 用。 */
+    private canvasWithCtxListeners;
     renderSystem: RendererSystem;
     rendererManager: RendererManager;
     containerManager: ContainerManager;
     init(): void;
+    /**
+     * T-N2 (Phase N):安装 visibility / WebGL context-loss listener。
+     *
+     * 安装姿势:
+     *   - visibility:`document.visibilitychange` → 更新 `isHidden`
+     *   - context loss:`canvas.webglcontextlost` → 设 `contextLost=true` + probe;
+     *                   `canvas.webglcontextrestored` → 清回 false
+     *
+     * 失败容忍:任何环境异常(jsdom 不支持某些 listener / renderSystem 还没初始化 application)
+     * 都静默 catch,不让 init 因此崩溃。
+     */
+    private installVisibilityHandlers;
+    /**
+     * T-N2:卸载 visibility / context-loss listener,destroy() 调用以避免内存泄漏。
+     */
+    private uninstallVisibilityHandlers;
+    /** Late probe attach — host can call this after `installPerfProbes` if init order isn't right. */
+    attachPerfProbes(probes: PerfProbeRegistry | null): void;
+    /**
+     * T-L7 (Phase L) public API:host 注入 viewport culling hint。
+     *
+     * - bounds 非 null:更新 record.cullingBoundsHint,下次 build 时 buildChunksForLayer 会
+     *   跳过不相交的 chunk。
+     * - null:清除 hint(等价于不剔除任何 chunk)。
+     *
+     * 本方法只更新字段,不强制重建。host 想立刻生效有两种姿势:
+     *   1. 调用后通过 `component.layersV2 = layersV2.slice()` 触发 observer rebuild
+     *   2. 调 `invalidateChunks` 标记 dirty 让 rAF flush 时按新 hint rebuild
+     * 这样 setHint 是 O(1),呼应性能预算。
+     */
+    setCullingBoundsHint(gameObjectId: number, bounds: {
+        minX: number;
+        minY: number;
+        maxX: number;
+        maxY: number;
+    } | null): void;
+    /**
+     * T-L4 (Phase L) public API:host 标记若干 chunk dirty,触发 rAF flush 增量重建。
+     *
+     * 触发场景:layer paint stroke 完成后 host 知道哪些 chunkKey 被改了,调本方法即可。
+     * 比 prop=layersV2 整体 reassign 高效得多(整 layer rebuild O(visibleChunks) → O(stroke)).
+     *
+     * 流程:
+     *   1. 把 chunkKeys 累加到 record.dirtyChunkKeys.get(layerId)
+     *   2. emit DIRTY_PENDING gauge(总 size)
+     *   3. 如果还没 scheduled,启动一次 rAF tick 在下一帧调 flushDirtyChunks
+     *
+     * 调用方应保证 chunkKey 形态与 cellData.chunks key 一致(如 "0,0")。未知 chunkKey
+     * 在 flush 时被静默忽略(已在 cellData.chunks 内会被处理;否则跳过)。
+     */
+    invalidateChunks(gameObjectId: number, layerId: string, chunkKeys: string[]): void;
+    /**
+     * T-L4 (Phase L):rAF callback;只 rebuild record.dirtyChunkKeys 内 chunk,不影响其他 chunk。
+     *
+     * 本方法是 public 供测试调用,但生产路径只走 invalidateChunks scheduled trigger。
+     * 行为:
+     *   - 找到 component 的 layersV2 layer for layerId
+     *   - 对每个 dirty chunkKey:destroy 旧 chunkContainer + 重新 populate
+     *   - emit DIRTY_FRAMES_BEHIND counter+1(本帧 flush 了 N 个 chunk 即"延迟一帧")
+     *   - 清空 dirtyChunkKeys + 把 DIRTY_PENDING gauge 归零
+     */
+    flushDirtyChunks(gameObjectId: number): void;
+    private probeBegin;
+    private probeEnd;
+    private probeCount;
+    private probeGauge;
     rendererUpdate(_gameObject: GameObject): void;
+    /**
+     * Eva.js update 调用(每帧)— 推进 v2 path animation tick。
+     * 任何 tile 切到新 frame 时,标记对应 chunk dirty,下一帧重建。
+     * v1 路径不参与(没 animation 元数据)。
+     *
+     * T-N1 (Phase N) hardening:
+     *   - 每个 driver advance 包在内层 try/catch:一个 entity 的 animation pipeline 抛错
+     *     不影响其他 entity 的 tick(continue 到下一个);失败计入 ANIM_TICK_ERROR_COUNT probe
+     *     并 console.error 留诊断。
+     *   - 外层 try/finally 包整段 hot path:保证 probeEnd(ANIM_TICK_MS) 一定 pair probeBegin,
+     *     不会因为内层逻辑泄漏 throw 导致 timing 计 inFlight 永远不释放。
+     *
+     * T-N2 (Phase N) hardening:
+     *   - tab hidden 或 WebGL context lost 时直接 early return,不浪费 CPU,且避免 context lost
+     *     期间渲染调用堆栈抛错。
+     */
+    update(_frame: unknown): void;
     componentChanged(changed: ComponentChanged): Promise<void>;
-    /** 销毁现有 layer/frame 纹理(切换 tileset 或卸载时调用)。 */
-    private tearDownChildren;
-    private buildLayers;
+    private handleAdd;
+    /**
+     * v1 path:load tileset texture + buildLayersV1。被 handleAdd 与 handleChange(mode upgrade)共用。
+     *
+     * 调用方负责:
+     *   - 在调用前设置 record.mode = 'v1'
+     *   - 在调用前 increaseAsyncId 拿到 asyncId
+     *   - record 在 records[gameObjectId] 已就位
+     *
+     * 本方法负责:
+     *   - resource.getResource(tileset)
+     *   - asyncId 校验(swap 期间 ref 被替换则中断)
+     *   - 错误日志
+     *   - 把 baseTexture 写回 record + buildLayersV1 + requestRedraw
+     */
+    private ensureV1Built;
+    /**
+     * v2 path:load tileset doc + atlas textures + animation driver + buildLayersV2。
+     * 被 handleAdd 与 handleChange(mode upgrade / tilemapRef swap)共用。
+     *
+     * 调用方负责:
+     *   - 在调用前设置 record.mode = 'v2'
+     *   - 在调用前 increaseAsyncId 拿到 asyncId
+     *   - 在调用前已 tearDown 旧 mode 的产物(如果是 mode upgrade)
+     */
+    private ensureV2Built;
+    /**
+     * Editor preview 的 PIXI ticker 在 edit 模式被冻结。Tilemap mount/hot-swap 完成时
+     * 主动 trigger 一帧让 chunk 立即可见。preserveDrawingBuffer:true 后单次 render 即可
+     * 定格(见 plugin-renderer/lib/System.ts createApplication 注释)。
+     */
+    private requestRedraw;
+    private handleChange;
+    private handleRemove;
+    private detectMode;
+    private loadV1Texture;
+    private tearDownChildrenV1;
+    private buildLayersV1;
+    private loadV2Tileset;
+    private loadAtlasTextures;
+    private tearDownChildrenV2;
+    private buildLayersV2;
+    private buildChunksForLayer;
+    /**
+     * 尝试用 mesh path 渲染 chunk(P1-3)。
+     *
+     * 当前实现策略:
+     * - 先检查 isMeshPathAvailable():当 false(本 cycle 默认),直接返回 false 让上层降级。
+     * - 当 true(后续 cycle 接入真实 shader 时):调 buildChunkMesh,把结果 add 到 chunkContainer。
+     *
+     * 出错 / 返回空容器一律视为不可用,返回 false 让 buildChunksForLayer 走 sprite 路径。
+     * 这样 "mesh path is dead code" 的局面变成 "mesh path 已 wired,降级有 probe 记录"。
+     */
+    private tryBuildMeshChunk;
+    private populateChunkSprites;
+    private getAtlasFrameTexture;
     destroy(): void;
 }
 
+export declare interface TilesetChunkRebuildDiff {
+    addedSources: TilesetSourceRaw[];
+    removedSourceIds: string[];
+    changedSourceIds: string[];
+    addedTilesByKey: Set<string>;
+    removedTilesByKey: Set<string>;
+    changedTilesByKey: Set<string>;
+}
+
+/**
+ * @deprecated Use `TilesetChunkRebuildDiff`. Alias kept for transitional
+ * compatibility; will be removed once consumers migrate.
+ */
+export declare type TilesetDiff = TilesetChunkRebuildDiff;
+
+/**
+ * TileSet 外链 .tileset.json 在运行时的 minimal type shape。
+ *
+ * 为避免反向依赖 libs/dsl,这里独立声明;与 libs/dsl/src/types/tileset.ts 的 disk schema 同形。
+ */
+export declare interface TilesetDocumentRaw {
+    kind: 'tileset';
+    schemaVersion: 1;
+    name: string;
+    version?: string;
+    tileSize: {
+        width: number;
+        height: number;
+    };
+    gridMode?: 'square' | 'isometric' | 'halfOffsetSquare' | 'hexagon';
+    sources: TilesetSourceRaw[];
+}
+
+declare type TilesetSourceRaw = {
+    kind: 'atlas';
+    id: string;
+    textureAsset: string;
+    regionSize: {
+        width: number;
+        height: number;
+    };
+    margins?: {
+        x: number;
+        y: number;
+    };
+    separation?: {
+        x: number;
+        y: number;
+    };
+    usePadding?: boolean;
+    tiles: AtlasTileRaw[];
+} | {
+    kind: 'sceneCollection';
+    id: string;
+    prefabRefs: string[];
+};
+
+/**
+ * 包成 PIXI.GlProgram options 形式 — host 用 `new Program({glProgram: ...})` 创建。
+ */
+export declare interface TileShaderSources {
+    vertex: string;
+    fragment: string;
+}
+
+/**
+ * 把局部 polygon 平移到目标 cell 的世界坐标。
+ * Phase 3 在 chunk rebuild 时调用,把 cached convex parts 复用到任意 cell 位置。
+ */
+export declare function translateConvexParts(parts: ConvexPart[], dx: number, dy: number): ConvexPart[];
+
+export declare function unpackCell(packed: number): CellRecord;
+
 export { }