Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

22.3 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file  importSettings.ts
 * @brief Single source of truth for per-type asset import settings (the `.meta`
 *        `importer` block). One registry produces both the import-time defaults
 *        and the fields an editor offers, so the two can't drift.
 *
 *        The specs carry their own presentation vocabulary rather than the
 *        editor's `InspectorField`: what a setting IS belongs to the project, and
 *        a build that never opens a window still has to read it. An editor maps
 *        a spec onto whatever control it renders.
 */

/** What an import setting can hold. Anything richer belongs in the asset, not here. */
export type ImporterValue = number | boolean | string;

/** The control kinds import settings need — a subset of what an inspector can render. */
export type ImporterFieldType = 'number' | 'bool' | 'string' | 'enum' | 'select';

/** A named choice for an `enum` field: the label shown, the value stored. A
 *  choice is never a flag — a two-state setting is a `bool`. */
export interface ImporterEnumOption {
  label: string;
  value: string | number;
}

/** One import setting: where it lives in the `importer` block, and how to offer it. */
export interface ImporterFieldSpec {
  /** Dotted path within the `importer` block (`sliceBorder.left`). */
  key: string;
  label: string;
  type: ImporterFieldType;
  /** Written into a fresh `.meta`, and the reset target of an editor's field. */
  default: ImporterValue;
  category?: string;
  tooltip?: string;
  /** Rarely edited — an editor may fold it away. */
  advanced?: boolean;
  min?: number;
  max?: number;
  step?: number;
  /** For `type: 'enum'`. */
  options?: ImporterEnumOption[];
  /** For `type: 'select'`. */
  selectOptions?: string[];
  /** What a stored value means today, for a field whose vocabulary has changed —
   *  applied wherever the block is read, so a `.meta` written before the change
   *  shows, and cooks, as what it now stands for. */
  read?: (stored: unknown) => ImporterValue;
}

const powerOfTwo = [256, 512, 1024, 2048, 4096, 8192];

const TEXTURE: ImporterFieldSpec[] = [
  {
    key: 'use', label: 'Use', type: 'enum', default: 'colour', category: 'Texture',
    options: [{ label: 'Colour', value: 'colour' }, { label: 'Data', value: 'data' }],
    read: textureUse,
    tooltip: 'What the image holds. Colour is a picture: a build may shrink it to Max Size, compress it and fill the colour under '
      + 'its clear texels. Data is numbers a texel, read as they are - a heightmap, a mask of measured values, a lookup table: a '
      + 'build keeps its depth (16 bits a sample stay 16), never compresses it or decodes it as sRGB, and shrinks it only when '
      + 'Max Size says so.',
  },
  {
    key: 'maxSize', label: 'Max Size', type: 'enum', default: 2048, category: 'Texture',
    options: [{ label: 'Source size', value: 0 }, ...powerOfTwo.map((n) => ({ label: String(n), value: n }))],
    tooltip: 'Downscale cap applied at cook (power of two). A source larger than this on '
      + 'its longest side is box-filtered down; smaller sources are untouched. Source size never shrinks it, which is what a '
      + 'Data texture starts at: half the samples of a heightmap is other ground.',
  },
  {
    key: 'compress', label: 'Compression', type: 'enum', default: 'auto', category: 'Texture',
    options: [
      { label: 'Auto (by use)', value: 'auto' },
      { label: 'GPU compressed', value: 'on' },
      { label: 'Original image', value: 'off' },
    ],
    read: textureCompression,
    tooltip: 'GPU compressed ships a KTX2 that stays compressed in video memory — about a '
      + 'quarter of the decoded image — and transcodes per device. Original image ships the '
      + 'file as it is: exact, and for flat art far smaller to download, but decoded in full '
      + 'on the GPU. Auto is GPU compressed for a texture a mesh draws and the original for '
      + 'sprites and UI. Only applies when the build compresses assets.',
  },
  {
    key: 'compressFormat', label: 'Compress Format', type: 'select', default: 'uastc',
    category: 'Texture', advanced: true, selectOptions: ['uastc', 'etc1s'],
    tooltip: 'UASTC — high quality, larger. ETC1S — much smaller, lower quality '
      + '(good for photographic / low-frequency art). Only used when Compress is on.',
  },
  {
    key: 'mipmaps', label: 'Mip Maps', type: 'bool', default: true, category: 'Texture',
    tooltip: 'Keep a chain of half-size copies so a texture drawn small samples a filtered image '
      + 'instead of shimmering. Costs a third more memory. Turn off for pixel art and UI that '
      + 'is always drawn at its own size.',
  },
  {
    key: 'filterMode', label: 'Filter', type: 'select', default: 'linear', category: 'Texture',
    selectOptions: ['nearest', 'linear'],
    tooltip: 'Texture sampling filter. Nearest keeps pixels crisp; Linear smooths.',
  },
  {
    key: 'wrapMode', label: 'Wrap', type: 'select', default: 'repeat', category: 'Texture',
    selectOptions: ['repeat', 'clamp', 'mirror'],
    tooltip: 'How UVs outside [0,1] are addressed.',
  },
  {
    key: 'sRGB', label: 'sRGB Color', type: 'bool', default: true, category: 'Texture', advanced: true,
    tooltip: 'The image stores sRGB-encoded color (albedo/UI). Disable for authored-linear '
      + 'data like normal maps and masks — only meaningful when the project renders in linear color.',
  },
  {
    key: 'alphaIsTransparency', label: 'Alpha Is Transparency', type: 'bool', default: true, category: 'Texture', advanced: true,
    tooltip: 'Fill the colour of fully clear texels from their solid neighbours when the texture is '
      + 'cooked, so filtering and mip maps at a transparent edge do not average in the black (or '
      + 'whatever was painted) under alpha 0 as a dark fringe. Partly clear and solid texels keep '
      + 'their colour, and premultiplied art is left as it is. Turn off for an image whose RGB under '
      + 'alpha 0 a shader reads as data.',
  },
  {
    key: 'mipCoverage', label: 'Mip Coverage Cutoff', type: 'number', default: 0, min: 0, max: 1, step: 0.01,
    category: 'Texture', advanced: true,
    tooltip: 'For a cutout (leaves, grass, fences): the alpha cutoff its material tests. Each mip '
      + 'level keeps the share of texels above it that the full image has, so the cutout does '
      + 'not thin out with distance. 0 = off. Applies to UASTC-compressed textures.',
  },
  { key: 'sliceBorder.left', label: 'Border Left', type: 'number', default: 0, min: 0, category: '9-Slice', advanced: true },
  { key: 'sliceBorder.right', label: 'Border Right', type: 'number', default: 0, min: 0, category: '9-Slice', advanced: true },
  { key: 'sliceBorder.top', label: 'Border Top', type: 'number', default: 0, min: 0, category: '9-Slice', advanced: true },
  { key: 'sliceBorder.bottom', label: 'Border Bottom', type: 'number', default: 0, min: 0, category: '9-Slice', advanced: true },
  // How this image is cut, declared ONCE on the sheet — not on every Sprite that
  // shows a frame of it, which is how four numbers become four disagreeing copies.
  // A cell size of 0 means "not a sheet", which is what most textures are.
  {
    key: 'sheet.cellWidth', label: 'Cell Width', type: 'number', default: 0, min: 0, category: 'Sheet',
    tooltip: 'Width of one cell, in pixels. 0 = this image is not a sprite sheet. '
      + 'Setting it lets a Sprite pick a frame of this image instead of showing all of it.',
  },
  { key: 'sheet.cellHeight', label: 'Cell Height', type: 'number', default: 0, min: 0, category: 'Sheet',
    tooltip: 'Height of one cell, in pixels. 0 = this image is not a sprite sheet.' },
  { key: 'sheet.margin', label: 'Margin', type: 'number', default: 0, min: 0, category: 'Sheet',
    tooltip: 'Padding before the first cell, on both axes.' },
  { key: 'sheet.spacing', label: 'Spacing', type: 'number', default: 0, min: 0, category: 'Sheet',
    tooltip: 'Gap between neighbouring cells. Paid between cells only, never after the last one.' },
];

// `cullingBounds` promises no pose of this skeleton leaves it. The runtime's
// demand-driven posing reads it: with a promise, a skeleton no camera can see
// may be left unposed. A rectangle of no area is the absence of one.
const SPINE: ImporterFieldSpec[] = [
  { key: 'scale', label: 'Scale', type: 'number', default: 1, min: 0, step: 0.01, category: 'Spine' },
  {
    key: 'cullingBounds.x', label: 'Culling X', type: 'number', default: 0,
    category: 'Culling', advanced: true,
    tooltip: 'Left edge of the area this skeleton promises to stay inside, in its own space. '
      + 'Width or height of zero means no promise, and the skeleton is posed every frame.',
  },
  { key: 'cullingBounds.y', label: 'Culling Y', type: 'number', default: 0, category: 'Culling', advanced: true },
  {
    key: 'cullingBounds.width', label: 'Culling Width', type: 'number', default: 0, min: 0,
    category: 'Culling', advanced: true,
    tooltip: 'Zero means no promise. A skeleton that leaves this area while it is '
      + 'in view can be culled while visible.',
  },
  { key: 'cullingBounds.height', label: 'Culling Height', type: 'number', default: 0, min: 0, category: 'Culling', advanced: true },
  {
    key: 'cullingAtlas', label: 'Culling Atlas', type: 'string', default: '',
    category: 'Culling', advanced: true,
    tooltip: 'The atlas this promise was made against — written by "Use as Fixed Culling '
      + 'Bounds", not by hand. A spine asset is a skeleton AND an atlas, so the same '
      + 'skeleton drawn with a different atlas inherits no promise. Empty means no promise.',
  },
];

// Which armature and animation an entity gets are DragonBonesAnimation fields
// (empty = the file's first / its setup pose), so import carries only the scale.
const DRAGONBONES: ImporterFieldSpec[] = [
  { key: 'scale', label: 'Scale', type: 'number', default: 1, min: 0, step: 0.01, category: 'DragonBones' },
];

const AUDIO: ImporterFieldSpec[] = [
  {
    key: 'loadType', label: 'Load Type', type: 'enum', default: 'auto', category: 'Audio',
    options: [
      { label: 'Auto', value: 'auto' },
      { label: 'Decompress On Load', value: 'decompress' },
      { label: 'Streaming', value: 'streaming' },
    ],
    tooltip: 'How the clip is held on Web. Auto streams clips of 30 seconds or longer and decodes shorter '
      + 'ones. Decompress On Load decodes to memory: instant to start, and a 3-minute track costs about 69 MB. '
      + 'Streaming plays from the compressed file and takes almost no memory, but cannot loop on an exact '
      + 'sample and plays one instance of the clip at a time.',
  },
  {
    key: 'compress', label: 'Compress', type: 'bool', default: true, category: 'Audio',
    tooltip: 'Re-encode WAV to MP3 at cook (already-compressed formats pass through). '
      + 'MP3 has a small encoder delay — disable for seamless-loop clips.',
  },
  {
    key: 'bitrateKbps', label: 'Bitrate', type: 'enum', default: 128, category: 'Audio',
    options: [96, 128, 192].map((n) => ({ label: `${n} kbps`, value: n })),
    tooltip: 'MP3 bitrate for cooked WAV sources.',
  },
];

// Playback (loop / autoplay / muted) belongs to the Video COMPONENT, which
// carries all three: an import-time copy of them was read by nothing.
const VIDEO: ImporterFieldSpec[] = [
  {
    key: 'quality', label: 'Cook Quality', type: 'number', default: 4, min: 2, max: 31, step: 1,
    category: 'Video', advanced: true,
    tooltip: 'MPEG-1 quantizer for targets on the wasm decode path (WeChat): '
      + '2 = near-lossless (largest file), 31 = smallest. Web targets ship the source untouched.',
  },
  {
    key: 'audioBitrateKbps', label: 'Cook Audio Bitrate', type: 'enum', default: 128,
    category: 'Video', advanced: true,
    options: [96, 128, 192].map((n) => ({ label: `${n} kbps`, value: n })),
    tooltip: 'AAC bitrate for the audio track demuxed at cook (wasm decode path).',
  },
];

const MODEL: ImporterFieldSpec[] = [
  {
    key: 'scale', label: 'Scale', type: 'number', default: 1, min: 0.0001, step: 0.1,
    category: 'Import',
    tooltip: 'Uniform scale on the imported prefab\u0027s root. A model is authored in metres '
      + 'whose real size in this project is set by its units per metre (Project Settings, Physics, 3D): '
      + 'a Scale of 100 by default, 1 in a metre project, brings it in at real size.',
  },
  {
    key: 'lightmapUV', label: 'Generate Lightmap UVs', type: 'bool', default: false,
    category: 'Import',
    tooltip: 'Unwrap a second UV set so this model can receive baked light. Off by default '
      + 'because it splits vertices and most models are never baked; skinned meshes never get '
      + 'one, and a model that already carries the channel keeps its own.',
  },
  {
    key: 'lodLevels', label: 'Generate LODs', type: 'enum', default: 0, category: 'Import',
    options: [{ label: 'Off', value: 0 }, { label: '1 level', value: 1 },
              { label: '2 levels', value: 2 }, { label: '3 levels', value: 3 }],
    tooltip: 'Simplify each mesh into cheaper stand-ins (about 50%, 20% and 7% of its '
      + 'triangles) and add a LODGroup that swaps them in as it shrinks on screen. Smaller '
      + 'meshes load faster and distant ones draw faster. Skinned and morphing meshes keep one level.',
  },
  {
    key: 'lodMinTriangles', label: 'LOD Minimum Triangles', type: 'number', default: 256, min: 0, step: 16,
    category: 'Import', advanced: true,
    tooltip: 'A mesh with fewer triangles than this gets no levels: there is too little to '
      + 'take out for a swap to pay.',
  },
  {
    key: 'characterMaterials', label: 'Character Materials', type: 'enum', default: 'off',
    category: 'Import', advanced: true,
    options: [{ label: 'Off', value: 'off' }, { label: 'By Material Name', value: 'auto' }],
    tooltip: 'Give materials whose names say skin, face, head, hair or eye the engine\u0027s Skin, Hair and Eye '
      + 'shaders instead of the Model shader, with the normal and occlusion/roughness maps bound to them, and hair '
      + 'cut out and feathered by its alpha. A name is a convention, so check what it chose.',
  },
  {
    key: 'springBones', label: 'Spring Bones', type: 'enum', default: 'off',
    category: 'Import', advanced: true,
    options: [{ label: 'Off', value: 'off' }, { label: 'From File Data and Names', value: 'auto' }],
    tooltip: 'Give hair its secondary motion from what the model already says. A VRM spring-bone extension or a node custom '
      + 'property (extras.estella.springBone / springCollider) is used as stated; for what they leave out, a bone called '
      + 'Hair_<region>_<chain>_00 becomes a SpringBone and an empty called SBC_Sphere_<name>_r<cm> or '
      + 'SBC_Capsule_<name>_r<cm>_h<cm> a collider. Sizes are in metres, as the model has them. A name is a convention, so check what it found.',
  },
  {
    key: 'specularMap', label: 'Specular Map', type: 'enum', default: 'color',
    category: 'Import', advanced: true,
    options: [{ label: 'Specular Color', value: 'color' }, { label: 'Packed ORM', value: 'orm' }],
    tooltip: 'What the source\u0027s specular map holds. Most files mean a highlight tint, which '
      + 'the engine\u0027s metal/rough shading has no slot for. Scenes authored for Falcor '
      + '(Bistro, Sun Temple) pack occlusion, roughness and metalness there instead; '
      + 'Packed ORM binds it as those three. FBX only.',
  },
];

const PANORAMA: ImporterFieldSpec[] = [
  {
    key: 'faceSize', label: 'Reflection Size', type: 'enum', default: 128, category: 'Import',
    options: [32, 64, 128, 256, 512].map((n) => ({ label: `${n} px`, value: n })),
    tooltip: 'Edge length of the sharpest prefiltered reflection. Larger keeps a mirror '
      + 'crisper and costs baking time and image bytes; the diffuse half is nine numbers either way.',
  },
  {
    key: 'skyWidth', label: 'Sky Width', type: 'enum', default: 2048, category: 'Import',
    options: [
      { label: 'No sky image', value: 0 },
      ...[1024, 2048, 4096].map((n) => ({ label: `${n} px`, value: n })),
    ],
    tooltip: 'Width of the panorama the sky is drawn from, kept at the resolution of the source up '
      + 'to this. Fine detail — stars, thin lines — needs more; a sky behind a dark scene needs '
      + 'less. The reflections are sized apart, by Reflection Size.',
  },
];

/** type → its import-setting field specs. Types absent here have no import
 *  settings (only metadata) and get an empty defaults object. */
export const IMPORTER_SCHEMAS: Record<string, ImporterFieldSpec[]> = {
  model: MODEL,
  panorama: PANORAMA,
  texture: TEXTURE,
  sprite: TEXTURE,
  // A picture's source named where a texture goes is sampled as one: its filter, its wrap and whether it is colour are a texture's.
  imageSource: TEXTURE,
  spine: SPINE,
  dragonbones: DRAGONBONES,
  audio: AUDIO,
  video: VIDEO,
};

/** Cook-facing audio import settings, tolerant of hand-edited `.meta` blocks. */
export function readAudioImportSettings(importer: Record<string, unknown> | undefined): {
  compress: boolean; bitrateKbps: number;
} {
  const compress = importer?.compress;
  const bitrate = importer?.bitrateKbps;
  return {
    compress: typeof compress === 'boolean' ? compress : true,
    bitrateKbps: bitrate === 96 || bitrate === 128 || bitrate === 192 ? bitrate : 128,
  };
}

export const getImporterValueByPath = (obj: Record<string, unknown>, path: string): unknown =>
  path.split('.').reduce<unknown>((o, k) => (o && typeof o === 'object' ? (o as Record<string, unknown>)[k] : undefined), obj);

export function setImporterValueByPath(obj: Record<string, unknown>, path: string, value: unknown): void {
  const keys = path.split('.');
  let cur = obj;
  for (let i = 0; i < keys.length - 1; i++) {
    const k = keys[i];
    if (!cur[k] || typeof cur[k] !== 'object') cur[k] = {};
    cur = cur[k] as Record<string, unknown>;
  }
  cur[keys[keys.length - 1]] = value;
}

/** The `importer` block written into a fresh `.meta` at import time — derived from
 *  the same specs an editor offers, so the two never drift. */
export function importerDefaults(type: string): Record<string, unknown> {
  const specs = IMPORTER_SCHEMAS[type];
  if (!specs) return {};
  const out: Record<string, unknown> = {};
  for (const s of specs) setImporterValueByPath(out, s.key, s.default);
  return out;
}

/** True when a type exposes editable import settings. */
export const hasImporterSettings = (type: string): boolean => (IMPORTER_SCHEMAS[type]?.length ?? 0) > 0;

/** Whether two asset types are edited by the SAME settings — a sprite and a
 *  texture are, so a selection spanning both is still one batch. Identity of the
 *  spec array, not of the type name: the table above is what decides it. */
export const sharesImporterSchema = (a: string, b: string): boolean =>
  IMPORTER_SCHEMAS[a] !== undefined && IMPORTER_SCHEMAS[a] === IMPORTER_SCHEMAS[b];

/** The texture cook settings a platform may override: size cap + whether/how to
 *  compress. sRGB is intrinsic to the asset's color rather than the target, so it
 *  is not overridable. `enabled` is the per-platform switch — an override applies
 *  only when it is on. */
export interface TexturePlatformOverride {
  enabled?: boolean;
  maxSize?: number;
  /** A TextureCompression, or the boolean an older `.meta` holds. */
  compress?: TextureCompression | boolean;
  compressFormat?: 'uastc' | 'etc1s';
}

/** Cook-facing texture settings, tolerant of hand-edited `.meta` blocks: each
 *  texture decides its own KTX2 format, opt-out and size cap. An ENABLED
 *  `importer.overrides[platform]` wins per field; an unset field inherits the
 *  default. Defaults match a fresh `.meta`. */
/** What a texture's Compression asks for. */
export type TextureCompression = 'auto' | 'on' | 'off';

/**
 * A stored Compression value as it reads today. It was a boolean, written true
 * into every fresh `.meta` whatever the texture was — so true means Auto, the
 * default it was standing for, and false the Original image someone turned it to.
 */
export function textureCompression(stored: unknown): TextureCompression {
  if (stored === 'on' || stored === 'off' || stored === 'auto') return stored;
  return stored === false ? 'off' : 'auto';
}

/** What a texture holds: a picture, or numbers a texel (the `use` import setting). */
export type TextureUse = 'colour' | 'data';

/** A stored Use as it reads today: anything that is not `data` is a picture. */
export function textureUse(stored: unknown): TextureUse {
  return stored === 'data' ? 'data' : 'colour';
}

export { DATA_TEXTURE_IMPORTER } from '../../../tools/assetMetaTable.js';

export function readTextureCookSettings(importer: Record<string, unknown> | undefined, platform?: string): {
  use: TextureUse; compress: TextureCompression; format: 'uastc' | 'etc1s'; maxSize: number; srgb: boolean; mipCoverage: number; mipmaps: boolean;
} {
  const use = textureUse(importer?.use);
  const compress = importer?.compress;
  const mipCoverage = importer?.mipCoverage;
  const format = importer?.compressFormat;
  const maxSize = importer?.maxSize;
  const srgb = importer?.sRGB;
  const data = use === 'data';
  const resolved = {
    use,
    // Numbers are never encoded, decoded as colour or averaged into a coverage: whatever the other rows say, Data says these.
    compress: data ? 'off' as TextureCompression : textureCompression(compress),
    format: (format === 'etc1s' ? 'etc1s' : 'uastc') as 'uastc' | 'etc1s',
    // 0 is the source's own size, stated. Unstated, a picture is capped at 2048 and numbers are not capped.
    maxSize: typeof maxSize === 'number' && maxSize >= 0 ? maxSize : data ? 0 : 2048,
    srgb: data ? false : typeof srgb === 'boolean' ? srgb : true,
    mipCoverage: !data && typeof mipCoverage === 'number' && mipCoverage > 0 && mipCoverage < 1 ? mipCoverage : 0,
    mipmaps: importer?.mipmaps !== false,
  };
  const overrides = importer?.overrides as Record<string, TexturePlatformOverride> | undefined;
  const ov = platform ? overrides?.[platform] : undefined;
  if (ov?.enabled) {
    if (ov.compress !== undefined && !data) resolved.compress = textureCompression(ov.compress);
    if (ov.compressFormat === 'etc1s' || ov.compressFormat === 'uastc') resolved.format = ov.compressFormat;
    if (typeof ov.maxSize === 'number' && ov.maxSize > 0) resolved.maxSize = ov.maxSize;
  }
  return resolved;
}

// Load-time settings (sampler + 9-slice border) are parsed by the SDK's
// `textureImportSettingsFrom`, not here: one reader for the editor and the
// shipped build, or the two disagree.