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.

14.1 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file  What a build target can render — and what it cannot.
 *
 * The editor authors every subsystem the engine has; a target does not necessarily
 * compile all of them, and this is where that is declared.
 *
 * The native app has no gap left: the flags `native/CMakeLists.txt` sets bring in the
 * whole engine source list, and the three optional runtimes that ship as emscripten
 * side modules on the web (Box2D, the Spine runtime, the video decoder) are compiled
 * into the host binary instead — a device has no dynamic-linking story to have. The
 * table stays because that can change: turn a flag off, or add a subsystem that only
 * one platform can host, and the entry belongs here so the export can name it rather
 * than writing a package that is quietly missing half a scene.
 *
 * Without this, an export writes a package that is quietly missing half a
 * scene. This is the one declaration of that gap, so the export can name it
 * instead. `pipeline/tests/target-support.test.ts` reads the native CMakeLists
 * and fails when the two drift: flipping a flag there is what deletes an entry
 * here.
 *
 * Deliberately free of node imports — the electron export and the renderer's
 * build dialog both read it.
 */
import { NATIVE_PLATFORMS, type ExportPlatform } from './platforms';

/** An engine subsystem a build target may lack. */
export type Subsystem =
    | 'text' | 'tilemap' | 'terrain' | 'foliage' | 'worldgen' | 'water' | 'spline' | 'voxel' | 'rig2d' | 'importedScene' | 'skeletalAnimation' | 'characterShaders' | 'timeline' | 'fxBasic' | 'fxAtmosphere' | 'fxLighting' | 'fxAgx' | 'particles' | 'postprocess' | 'physics' | 'physics3d'
    | 'spine' | 'dragonbones' | 'video' | 'ai' | 'logic' | 'replication' | 'gameplay' | 'textureRecipe';

/**
 * The authored vocabulary that puts a subsystem in use: a scene or prefab
 * carrying one of these components needs it at runtime. Scanning the serialized
 * content is what makes the warning specific — a project that never authors a
 * tilemap hears nothing about tilemaps.
 */
export const SUBSYSTEM_COMPONENTS: Readonly<Record<Subsystem, readonly string[]>> = {
    text: ['Text', 'BitmapText'],
    // No component: a package reaches it by shipping a texture that is a recipe (an .esimage), which the walk of what ships sees.
    textureRecipe: [],
    tilemap: ['Tilemap', 'TilemapLayer'],
    terrain: ['Terrain'],
    timeline: ['TimelinePlayer'],
    // Effects are named by the volume that carries them, not by a component: see {@link POST_PROCESS_EFFECT_GROUP}.
    fxBasic: [],
    fxAtmosphere: ['Weather', 'TimeOfDay'],
    fxLighting: [],
    fxAgx: [],
    foliage: ['Foliage', 'PlacedFoliage', 'FoliageContact', 'PlantProxy'],
    worldgen: ['WorldGen', 'WorldZone'],
    water: ['WaterBody', 'WaterZone', 'Floating'],
    spline: ['Spline', 'PathFollower', 'TerrainBand2D', 'RoadDecal'],
    voxel: ['VoxelTerrain'],
    rig2d: ['Bone2D', 'IK2D', 'BoneConstraint2D'],
    importedScene: ['NodeVisibility', 'ParticleModelUnits'],
    skeletalAnimation: ['Animator', 'AnimatorRootMotion', 'GripPose', 'GripSurface', 'GripProfile', 'GripHolder'],
    // Hair, Skin and Eye are shaders, not components: a character's materials are what name them (see SHADER_SUBSYSTEM).
    characterShaders: [],
    particles: ['ParticleEmitter', 'ParticleForceField', 'ParticleCollider'],
    postprocess: ['PostProcessVolume'],
    physics: [
        'RigidBody2D', 'BoxCollider2D', 'CircleCollider2D', 'CapsuleCollider2D', 'SegmentCollider2D',
        'PolygonCollider2D', 'ChainCollider2D', 'OneWayPlatform2D', 'CharacterController2D', 'PlatformerController2D',
        'HingeJoint2D', 'DistanceJoint2D', 'SliderJoint2D', 'FixedJoint2D', 'WheelJoint2D', 'MotorJoint2D',
    ],
    physics3d: [
        'RigidBody3D', 'BoxCollider3D', 'SphereCollider3D', 'CapsuleCollider3D',
        'MeshCollider3D', 'ConvexCollider3D', 'CharacterController3D',
        'HingeJoint3D', 'DistanceJoint3D', 'SliderJoint3D', 'FixedJoint3D', 'PointJoint3D', 'SwingTwistJoint3D', 'SixDOFJoint3D', 'Ragdoll', 'RagdollJoint',
    ],
    spine: ['SpineAnimation'],
    dragonbones: ['DragonBonesAnimation'],
    logic: ['ScriptGraphAgent'],
    video: ['Video'],
    ai: [
        'NavAgent', 'NavArea', 'NavLink', 'NavObstacle', 'NavVolume',
        'Perceiver', 'Perception', 'StateMachineAgent', 'BehaviorTreeAgent',
    ],
    replication: ['Replicated', 'NetGhost'],
    gameplay: [
        'ThirdPersonController', 'ThirdPersonCamera', 'FirstPersonController', 'FirstPersonViewModel', 'Health', 'MeleeAttack', 'Hunter', 'Playthrough',
    ],
};

/**
 * Which group carries the shaders of each built-in post-process effect. A `PostProcessVolume` names its effects by `type`, so this
 * is the evidence a scene gives; an effect a script adds by code is reached by importing the group's subpath.
 */
export const POST_PROCESS_EFFECT_GROUP: Readonly<Record<string, Subsystem>> = {
    blur: 'fxBasic', bloom: 'fxBasic', vignette: 'fxBasic', grayscale: 'fxBasic', colorGrade: 'fxBasic',
    chromaticAberration: 'fxBasic', tonemap: 'fxBasic', fxaa: 'fxBasic', lensDistortion: 'fxBasic', pixelate: 'fxBasic',
    outline: 'fxBasic', depthOutline: 'fxBasic', edgeOutline: 'fxBasic', lutGrade: 'fxBasic', palette: 'fxBasic', agx: 'fxAgx', sharpen: 'fxBasic', filmGrain: 'fxBasic',
    motionBlur: 'fxBasic', lensFlare: 'fxBasic',
    mist2d: 'fxAtmosphere', rain2d: 'fxAtmosphere', fog2d: 'fxAtmosphere', distanceFog: 'fxAtmosphere', skyAtmosphere: 'fxAtmosphere', heightFog: 'fxAtmosphere', rain: 'fxAtmosphere',
    voxelGI: 'fxLighting', ssgi: 'fxLighting', contactShadows: 'fxLighting', lightShafts: 'fxLighting',
    autoExposure: 'fxLighting', depthOfField: 'fxLighting', ssao: 'fxLighting', subsurface: 'fxLighting',
    gtao: 'fxLighting', ssr: 'fxLighting', taa: 'fxLighting',
    underwater: 'water',
};

/**
 * Which module carries each built-in shader that is not the core's. A material names its shader by `shader: 'builtin:<id>'`, so a project that authors one
 * uses the module that ships it — with no component in a scene to say so (a Water material on a plain mesh, a character's Hair).
 */
export const SHADER_SUBSYSTEM: Readonly<Record<string, Subsystem>> = {
    'builtin:water': 'water', 'builtin:terrain': 'terrain', 'builtin:foliage': 'foliage', 'builtin:voxel-ground': 'voxel',
    'builtin:hair': 'characterShaders', 'builtin:skin': 'characterShaders', 'builtin:eye': 'characterShaders',
};

/** Human name, for a message someone packaging a game has to act on. */
export const SUBSYSTEM_LABEL: Readonly<Record<Subsystem, string>> = {
    text: 'Text',
    textureRecipe: 'Texture recipes (pictures drawn on the device)',
    tilemap: 'Tilemaps',
    terrain: 'Terrain',
    timeline: 'Timelines',
    fxBasic: 'Post-process effects (colour, lens, edges)',
    fxAtmosphere: 'Post-process effects (sky, fog, rain)',
    fxLighting: 'Post-process effects (occlusion, reflections, exposure)',
    fxAgx: 'Post-process effect (AgX view transform and its tables)',
    foliage: 'Foliage',
    worldgen: 'Generated worlds (biomes, zones, placement)',
    water: 'Water',
    spline: 'Splines',
    voxel: 'Voxel terrain',
    rig2d: '2D rig constraints',
    importedScene: 'Imported scene (node visibility, particle units)',
    skeletalAnimation: 'Skeletal animation (animator, grip poses)',
    characterShaders: 'Character shaders (hair, skin, eye)',
    particles: 'Particles',
    postprocess: 'Post-processing',
    physics: 'Physics (Box2D)',
    physics3d: 'Physics (3D)',
    spine: 'Spine animation',
    dragonbones: 'DragonBones animation',
    logic: 'Script graphs',
    video: 'Video',
    ai: 'Gameplay AI',
    replication: 'Replication',
    gameplay: 'Gameplay (character, combat)',
};

/**
 * What a package on a LEAN entry does to get this subsystem back: import the
 * named specifier, nothing (`base`), or take the whole entry (`whole-entry` —
 * no subpath installs it yet). Beside the components that put each subsystem in
 * use, so adding one cannot leave the packaging question unanswered.
 */
export const SUBSYSTEM_INSTALL: Readonly<Record<Subsystem, string>> = {
    text: 'base',
    textureRecipe: 'esengine/image',
    particles: 'base',
    postprocess: 'base',
    tilemap: 'esengine/tilemap',
    terrain: 'esengine/terrain',
    timeline: 'esengine/timeline',
    fxBasic: 'esengine/fx-basic',
    fxAtmosphere: 'esengine/fx-atmosphere',
    fxLighting: 'esengine/fx-lighting',
    fxAgx: 'esengine/fx-agx',
    foliage: 'esengine/foliage',
    worldgen: 'esengine/worldgen',
    water: 'esengine/water',
    spline: 'esengine/spline',
    voxel: 'esengine/voxel',
    rig2d: 'esengine/rig2d',
    importedScene: 'esengine/imported-scene',
    skeletalAnimation: 'esengine/skeletal-animation',
    characterShaders: 'esengine/character-shaders',
    physics: 'esengine/physics',
    physics3d: 'esengine/physics3d',
    spine: 'esengine/spine',
    dragonbones: 'esengine/dragonbones',
    logic: 'esengine/logic',
    video: 'whole-entry',
    ai: 'esengine/ai',
    replication: 'esengine/replication',
    gameplay: 'esengine/gameplay',
};

/**
 * The cmake option whose absence drops a subsystem from a build of the engine
 * core (see `cmake/ESEngineSources.cmake`). The others ship as separate modules
 * and have no flag, so they are absent here.
 */
export const SUBSYSTEM_CMAKE_FLAG: Readonly<Partial<Record<Subsystem, string>>> = {
    text: 'ES_ENABLE_BITMAP_TEXT',
    tilemap: 'ES_ENABLE_TILEMAP',
    particles: 'ES_ENABLE_PARTICLES',
    postprocess: 'ES_ENABLE_POSTPROCESS',
};

/** A subsystem a target cannot run, and why. */
export interface SubsystemGap {
    subsystem: Subsystem;
    why: string;
}

/** What the native app cannot render — currently nothing. ONE list: iOS and Android
 *  compile the same `native/CMakeLists.txt`, so a flag flipped there opens or closes
 *  the gap on both. `pipeline/tests/target-support.test.ts` reads that file and fails
 *  when the two disagree. */
const NATIVE_GAPS: readonly SubsystemGap[] = [];

/**
 * Per-target gaps. A platform absent from this table has none *known*: only the
 * native targets' feature set has been audited against the engine's, since they
 * are the ones that compile a subset.
 */
const GAPS: Partial<Record<ExportPlatform, readonly SubsystemGap[]>> = Object.fromEntries(
    NATIVE_PLATFORMS.map((platform) => [platform, NATIVE_GAPS]),
);

/** What `platform` cannot render, whether or not this project uses it. */
export function targetGaps(platform: ExportPlatform): readonly SubsystemGap[] {
    return GAPS[platform] ?? [];
}

const COMPONENT_SUBSYSTEM: ReadonlyMap<string, Subsystem> = new Map(
    (Object.entries(SUBSYSTEM_COMPONENTS) as [Subsystem, readonly string[]][])
        .flatMap(([subsystem, names]) => names.map((name) => [name, subsystem] as const)),
);

/**
 * The `esengine/` module a component belongs to, or null for one the base engine
 * always carries. What the Add Component menu asks before offering a component a
 * project has refused — the same table the export refuses a build by.
 */
export function moduleOfComponent(name: string): string | null {
    const subsystem = COMPONENT_SUBSYSTEM.get(name);
    if (subsystem === undefined) return null;
    const install = SUBSYSTEM_INSTALL[subsystem];
    return install === 'base' || install === 'whole-entry' ? null : install;
}

/**
 * Collect the subsystems a scene / prefab document puts in use. Pure, and shape-
 * agnostic: it walks for the serialized `type` vocabulary, so nested entities,
 * prefab bodies and overrides are all seen without knowing the document layout.
 */
export function collectSubsystems(doc: unknown, into: Set<Subsystem> = new Set()): Set<Subsystem> {
    if (Array.isArray(doc)) {
        for (const item of doc) collectSubsystems(item, into);
        return into;
    }
    if (doc === null || typeof doc !== 'object') return into;
    const rec = doc as Record<string, unknown>;
    if (typeof rec.type === 'string') {
        const subsystem = COMPONENT_SUBSYSTEM.get(rec.type);
        if (subsystem) into.add(subsystem);
        // A material names the built-in shader it is made from.
        if (rec.type === 'material' && typeof rec.shader === 'string') {
            const shaderSubsystem = SHADER_SUBSYSTEM[rec.shader];
            if (shaderSubsystem) into.add(shaderSubsystem);
        }
        // A volume's effects are named in its data, and each is carried by one group.
        if (rec.type === 'PostProcessVolume') collectEffectGroups(rec.data, into);
    }
    for (const value of Object.values(rec)) collectSubsystems(value, into);
    return into;
}

function collectEffectGroups(data: unknown, into: Set<Subsystem>): void {
    const effects = (data as { effects?: unknown } | null)?.effects;
    if (!Array.isArray(effects)) return;
    for (const effect of effects) {
        const type = (effect as { type?: unknown } | null)?.type;
        const group = typeof type === 'string' ? POST_PROCESS_EFFECT_GROUP[type] : undefined;
        if (group) into.add(group);
    }
}

/** How many source files a warning names before it summarizes the rest. */
const MAX_NAMED_FILES = 3;

/**
 * One warning per subsystem this target cannot render but the shipped content
 * uses, naming where it came from. `usage` maps a subsystem to the files that
 * authored it (project-relative).
 */
export function subsystemGapWarnings(
    platform: ExportPlatform,
    usage: ReadonlyMap<Subsystem, readonly string[]>,
    /** The gaps to report; defaults to this platform's declared ones. Overridable so
     *  the reporting can be exercised while no target actually has a gap. */
    gaps: readonly SubsystemGap[] = targetGaps(platform),
): string[] {
    const warnings: string[] = [];
    for (const gap of gaps) {
        const files = usage.get(gap.subsystem);
        if (!files || files.length === 0) continue;
        const named = [...files].sort();
        const shown = named.slice(0, MAX_NAMED_FILES).join(', ');
        const rest = named.length > MAX_NAMED_FILES ? ` (+${named.length - MAX_NAMED_FILES} more)` : '';
        warnings.push(
            `${platform}: ${SUBSYSTEM_LABEL[gap.subsystem]} will not render in this build — ${gap.why}. Used by ${shown}${rest}`,
        );
    }
    return warnings;
}