logic export zh

src/logic/export.ts — 导出约定与序列化

纯逻辑，把轨道大组下的分组映射成 Create/Kuayue 的模型文件命名，并生成对应的 blockstates JSON。 零依赖，可在 Node 中单测。

导出模式（见 EXPORT_MODES）：new_java（1.21.11+，format_version，多轴 {x,y,z}）、 classic_java（1.21.11-，无 format_version，仅单轴）、bedrock（minecraft:geometry）、obj （单一合并网格 OBJ）。无法导出的元素回退 OBJ（判定见 groupNeedsObj）。

导出模式

export type ExportMode = 'new_java' | 'classic_java' | 'bedrock' | 'obj';

// id / 标签 / 判定说明（标签与说明经 i18n 本地化）
export const EXPORT_MODES: { id: ExportMode; label: string; description: string }[];

平台无关元素描述符

供 Blockbench 层从 live Cube / Mesh 抽取后传给纯函数。面纹理用稳定的 textureKey（Blockbench 层把 Texture 实例映射成 't0'/'t1'…）。

export interface ExportFaceData {
	uv?: [number, number, number, number];
	rotation?: number;
	textureKey?: string;
}

export interface ExportCubeData {
	name?: string;
	from: Vec3;
	to: Vec3;
	rotation?: Vec3;
	origin?: Vec3;
	faces: Partial<Record<CubeFaceDirection, ExportFaceData>>;
}

export interface ExportMeshFaceData {
	vertices: string[];
	uv?: number[] | Record<string, number[]>;  // 逐顶点 UV：数组（按 face.vertices 顺序）或对象（按顶点 id）
	textureKey?: string;
}

export interface ExportMeshData {
	name?: string;
	vertices: Record<string, Vec3>;
	faces: Record<string, ExportMeshFaceData>;
}

export type ExportElement = ({ type: 'cube' } & ExportCubeData) | ({ type: 'mesh' } & ExportMeshData);

export interface ExportTexture {
	key: string;
	resName: string;
	width: number;
	height: number;
	dataUrl?: string;  // base64 data URL（写 PNG 用；纯逻辑层不依赖）
}

判定与旋转序列化

// 判定分组在给定模式下是否「无法导出」而回退 OBJ：obj 模式全部回退；任一 mesh 元素（三角面）；
// classic_java 且任一立方体多轴旋转；bedrock 且引用 >1 张纹理
export function groupNeedsObj(elements: ExportElement[], mode: ExportMode): boolean;

// 元素旋转 → Java 模型 JSON 的 rotation 字段：无旋转 → undefined（不写）；new_java 且（多轴或任一角
// >45°）→ {x,y,z,origin}；否则单轴 → {angle,axis,origin}
export function rotationToJava(
	rotation: Vec3 | undefined,
	origin: Vec3 | undefined,
	mode: ExportMode
): { angle?: number; axis?: 'x' | 'y' | 'z'; x?: number; y?: number; z?: number; origin: Vec3 } | undefined;

命名映射

// 轨道形状分组 id → 导出模型文件名；null = 不单独导出。z_ortho 不导出（blockstates 用 x_ortho 旋转
// 90° 表达）；ascending_* 只导出南向 ascending.json；teleport_x 不导出；四个交叉模型全部导出
// （cross_d1_* = 正对角、cross_d2_* = 负对角；zo = 基础「对角 + Z 直轨」，xo = 其旋转 90°——对角 + X），
// 与参考 Kuayue standard assets 一致。
export const TRACK_MODEL_FILES: Record<string, string | null>;

export function cleanGroupName(name: string): string;          // 去掉「（…）」/「(…)」展示后缀
export function modelFileName(id: string): string | null;      // 由形状 id 取导出文件名
export function blockstatesFileName(trackId: string): string;  // {轨道id}_track.json

// 去掉扩展名、小写、非 [a-z0-9_] → _，并在 used 内保证唯一（重名追加 _1/_2…）
export function textureResourceName(name: string, used: Set<string>): string;

// 模型内纹理路径：{命名空间}:{纹理资源路径}/{资源名}（缺省 block/track/{轨道id}）
export function textureResourcePath(namespace: string, trackId: string, resName: string, texturePath?: string): string;

blockstates

// 变体组合 = shape × turn × waterlogged；shape=none → 空气模型，其余指向 {命名空间}:{模型资源路径}/
// {模型}（缺省 block/track/{轨道id}）。shape=zo → x_ortho y:90；四个交叉方向直接引用四个交叉模型
// （无 y 旋转）：cr_pdx→cross_d1_xo、cr_pdz→cross_d1_zo、cr_ndx→cross_d2_xo、cr_ndz→cross_d2_zo。
export function buildBlockstates(
	namespace: string,
	trackId: string,
	modelPath?: string
): { variants: Record<string, { model: string; y?: number }> };

Java 模型 JSON

// new_java 加 format_version 1.21.11 + 多轴 {x,y,z}；classic_java 不加 format_version、仅单轴旋转。
// 传入 elements 应为已判定可导出的立方体（mesh 已回退 OBJ）；UV 从像素换算为 16 单位制。
export function buildJavaModelJson(opts: {
	mode: ExportMode;
	elements: ExportElement[];
	textures: ExportTexture[];
	textureSize: [number, number];
	namespace: string;
	trackId: string;
	texturePathOf?: Record<string, string>;  // texture key → 资源目录（缺省 block/track/{trackId}）
}): Record<string, unknown>;

OBJ 引用 JSON

.obj/.mtl 的序列化在组装层（src/build/export.ts → exportGroupAsObj）；本函数构建 forge:obj 引用 JSON（.obj 模型 + flip_v + textures），与 Create/Kuayue 示例一致。

export function buildObjReferenceJson(opts: {
	namespace: string;
	trackId: string;
	shape: string;
	textures: ExportTexture[];
	texturePathOf?: Record<string, string>;
	modelPath?: string;   // 模型资源路径（blockstates 引用用），缺省 block/track/{trackId}
}): Record<string, unknown>;

基岩版

// 立方体 → minecraft:geometry 方块模型。参考 Blockbench o6/r6：立方体 origin[0] 取反（X 镜像）、
// 带旋转时 pivot=旋转原点（X 镜像）+ rx/ry 取反；per-face uv，up/down 面 uv+=size、size 取反。
// elements 应为已判定可导出的立方体（mesh / 多纹理已回退 OBJ）。
export function buildBedrockGeometry(opts: {
	identifier: string;
	elements: ExportElement[];
	textureSize: [number, number];
}): Record<string, unknown>;

// blocks.json（行为包根目录，legacy 聚合格式）：每形状一个块，identifier {ns}:{trackId}_{shape}；
// texturePath 相对 textures/ 目录（写入 textures/{texturePath}.png → "{texturePath}"）。
export function buildBedrockBlocksJson(opts: {
	namespace: string;
	trackId: string;
	shapes: { id: string; texturePath: string }[];
}): Record<string, unknown>;

---

← 返回中文接口文档