logic types zh

src/logic/types.ts — 纯类型定义

逻辑层与 Blockbench 之间的解耦枢纽。本模块零依赖，可在 Node 中直接单测。

基础类型

export type Vec3 = [number, number, number];
export type CubeFaceDirection = 'north' | 'south' | 'east' | 'west' | 'up' | 'down';

纹理与面

SourceTexture

源纹理：从 .bbmodel / 当前项目提取，用于导入到新工作区并应用到对应面。key 是源模型内的唯一 标识（.bbmodel 的 texture id，或当前项目的纹理 UUID）；CubeSpec 面的 texture 字段引用它， assembly 层据此映射到新工作区导入的 Texture。

export interface SourceTexture {
	key: string;        // 源模型内的唯一键
	name: string;
	source: string;     // 位图数据：base64 data URL 或桌面文件路径
	width: number;
	height: number;
}

FaceSpec

面 UV 描述（透传给 Blockbench CubeFace）。

export interface FaceSpec {
	uv?: [number, number, number, number];
	rotation?: number;
	texture?: string;   // 源纹理 key（见 SourceTexture），由 assembly 层映射到导入的 Texture
}

MeshFaceSpec

mesh 组的面：一组顶点 id + UV + 源纹理 key。uv 直接透传 .bbmodel 原始结构（顶点 UV 列表， 数组或对象均可），创建 Mesh 时原样交还 Blockbench 解释。

export interface MeshFaceSpec {
	vertices: string[];                 // 组成该面的顶点 id 列表（按逆时针顺序）
	uv?: number[] | Record<string, any>; // 顶点 UV（透传，不做任何修改）
	rotation?: number;
	texture?: string;                   // 源纹理 key（见 SourceTexture）
}

立方体与网格

CubeSpec

立方体的平台无关描述，与 Blockbench 的 ICubeOptions 对应。from/to 为盒子两个对角（px）， rotation 为绕 origin 的三轴旋转角（度）。

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

MeshSpec

mesh 组元素（.bbmodel 中 type 为 'mesh'）：顶点 id → 位置，面 id → 面。

export interface MeshSpec {
	name?: string;
	vertices: Record<string, Vec3>;
	faces: Record<string, MeshFaceSpec>;
	origin?: Vec3;
	rotation?: Vec3;
}

零件模型

PartModel

从 .bbmodel / 当前项目解析出的零件。归一化约定：底面 y = 0，轨道横向中线 x = 0。cubes 用于 生成轨道形状；meshes 仅用于工作区基础分组。

export interface PartModel {
	cubes: CubeSpec[];
	meshes?: MeshSpec[];          // mesh 元素（type='mesh'），有则说明该零件含网格组
	hasMesh?: boolean;            // 决定新工作区是否为自由模型
	bbox: { min: Vec3; max: Vec3 }; // 归一化后的包围盒（含 cube 与 mesh 顶点）
	xMid: number;                 // 横向中线 x 值（归一化后通常为 0）
	textureSize?: [number, number]; // 纹理分辨率 [w, h]（px）。三个零件必须一致，否则拒绝生成
	textures?: SourceTexture[];   // 零件引用的全部源纹理
}

配置

PortalConfig

传送门配置（可选）：两张纹理独立可选。trackTexture（portal_track）铺 teleport 形状的轨道/枕木 （缺省用零件默认纹理）；mipTexture（portal_track_mip）生成两个覆层块 teleport_left / teleport_right 把枕木左/右半边包住（不含钢轨）（缺省不生成）。结构参考 Create 原版 teleport.json。

export interface PortalConfig {
	trackTexture?: string;          // portal_track 纹理源 key（已带前缀，如 'P/track'）
	mipTexture?: string;            // portal_track_mip 纹理源 key（已带前缀，如 'P/mip'）
	mipTextureSize?: [number, number]; // 覆层（mip）纹理尺寸 [w, h]（px），缺省 32×32
	margin?: number;                // 覆层相对枕木外缘的包覆余量（px，避免共面闪烁），缺省 0.1
}

TrackConfig

生成轨道所需的全部输入。

export interface TrackConfig {
	gaugePx: number;          // 轨距（px，1/16 方块）＝左右钢轨中心距
	heightPx: number;         // 轨道距模型底面的高度（px，1/16 方块）
	wholeModelYOffset?: number; // 整个模型（含枕木与轨道）的 y 偏移（px），默认 0
	parts: {
		left: PartModel;
		right: PartModel;
		tie: PartModel;
	};
	portal?: PortalConfig;    // 传送门配置（可选）：两张纹理独立可选
}

形状结果

ShapeSpec

一种轨道形状的生成结果。meshes 把零件的 mesh 几何与 cube 一样摆放/旋转，纯 mesh 零件因此出现在 所有方向形状里，而不只在基础分组。

export interface ShapeSpec {
	id: string;     // TrackShape 标识，如 'x_ortho'、'diag'、'ascending_south'
	name: string;   // 展示名（Group 名）
	cubes: CubeSpec[];
	meshes?: MeshSpec[];  // 零件贡献的 mesh 几何，与 cube 一样摆放/旋转进每个方向形状
}

---

← 返回中文接口文档