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.

17.0 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
//
// The .xcodeproj an iOS export ships, written directly.
//
// An export has to be something a user can double-click, the way Unity and Godot
// hand back a complete Xcode project — not a content folder plus instructions to
// install xcodegen and run it. The project's shape is fixed (one app target, one
// xcframework, the export's own files as resources), so generating the pbxproj is
// a template, and templating it here is what removes the external tool from the
// path between "Build" and "Run".
//
// Object ids are derived from their role, so re-exporting a project rewrites the
// same file byte-for-byte instead of churning a diff.

import { createHash } from 'crypto';

/** A pbxproj object id: 24 uppercase hex chars, stable for a given role. */
function oid(role) {
    return createHash('md5').update(role).digest('hex').slice(0, 24).toUpperCase();
}

// pbxproj is OpenStep plist. A bare word may only be alphanumerics, `_`, `.` and
// `/` — notably NOT `$` or parentheses, so build-setting references like
// `$(inherited)` have to be quoted or the whole file fails to parse.
function q(value) {
    const s = String(value);
    return s !== '' && /^[A-Za-z0-9_./]+$/.test(s)
        ? s
        : `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
}

function settingsBlock(settings, indent) {
    const pad = '\t'.repeat(indent);
    return Object.entries(settings)
        .map(([k, v]) => (Array.isArray(v)
            ? `${pad}${k} = (\n${v.map((i) => `${pad}\t${q(i)},`).join('\n')}\n${pad});`
            : `${pad}${k} = ${q(v)};`))
        .join('\n');
}

// The system frameworks the host links. Passed as linker flags rather than as file
// references: they add nothing a reader of the project navigator wants to see, and
// each one would otherwise cost a PBXFileReference + PBXBuildFile pair.
const SYSTEM_FRAMEWORKS = [
    'UIKit', 'Metal', 'QuartzCore', 'IOSurface', 'CoreGraphics',
    // Core Text names the font file the glyph rasterizer parses.
    'CoreText', 'Foundation',
    // miniaudio's CoreAudio backend, linked at build time (MA_NO_RUNTIME_LINKING).
    'AVFoundation', 'CoreAudio', 'AudioToolbox', 'CoreMotion', 'CoreHaptics',
];

/** Xcode's file type for an export resource, by extension. `folder` ships a
 *  directory as-is, keeping the cooked tree's shape inside the bundle. */
function fileType(name, isDir) {
    // An asset catalog is a directory Xcode COMPILES (actool) rather than copies —
    // which is the whole reason the app icon goes through one: since iOS 11 the
    // store takes icons no other way.
    if (name.endsWith('.xcassets')) return 'folder.assetcatalog';
    if (isDir) return 'folder';
    if (name.endsWith('.json')) return 'text.json';
    if (name.endsWith('.js')) return 'sourcecode.javascript';
    return 'file';
}

/**
 * Render the project.pbxproj for an exported game.
 *
 * @param {object} o
 * @param {string} o.name        Target + product name (the app's display name, sanitized).
 * @param {string} o.bundleId    PRODUCT_BUNDLE_IDENTIFIER.
 * @param {string} o.version     MARKETING_VERSION.
 * @param {number|string} o.versionCode  CURRENT_PROJECT_VERSION.
 * @param {string} o.deploymentTarget    IPHONEOS_DEPLOYMENT_TARGET.
 * @param {string} o.frameworkName       The xcframework's filename, at the project root.
 * @param {Array<{name: string, isDir: boolean}>} o.resources
 *        The export's own files, copied into the bundle root — where the host looks
 *        for them (it reads the bundle root, so no Content/ indirection).
 * @returns {string} project.pbxproj contents
 */
export function renderPbxproj(o) {
    const deploymentTarget = o.deploymentTarget ?? '17.0';
    const ids = {
        project: oid('project'),
        target: oid('target'),
        mainGroup: oid('group.main'),
        appGroup: oid('group.app'),
        productsGroup: oid('group.products'),
        product: oid('file.product'),
        mainSource: oid('file.main.m'),
        infoPlist: oid('file.Info.plist'),
        framework: oid(`file.${o.frameworkName}`),
        sourcesPhase: oid('phase.sources'),
        frameworksPhase: oid('phase.frameworks'),
        resourcesPhase: oid('phase.resources'),
        buildMain: oid('build.main.m'),
        buildFramework: oid(`build.${o.frameworkName}`),
        projectConfigList: oid('configlist.project'),
        targetConfigList: oid('configlist.target'),
        projectDebug: oid('config.project.Debug'),
        projectRelease: oid('config.project.Release'),
        targetDebug: oid('config.target.Debug'),
        targetRelease: oid('config.target.Release'),
    };
    const resources = o.resources.map((r) => ({
        ...r,
        fileId: oid(`file.res.${r.name}`),
        buildId: oid(`build.res.${r.name}`),
    }));

    const projectCommon = {
        ALWAYS_SEARCH_USER_PATHS: 'NO',
        CLANG_ENABLE_OBJC_ARC: 'YES',
        CLANG_ENABLE_MODULES: 'YES',
        COPY_PHASE_STRIP: 'NO',
        ENABLE_STRICT_OBJC_MSGSEND: 'YES',
        GCC_NO_COMMON_BLOCKS: 'YES',
        IPHONEOS_DEPLOYMENT_TARGET: deploymentTarget,
        SDKROOT: 'iphoneos',
        // arm64 only, device and simulator alike: the engine and Dawn are both
        // built arm64, so no x86_64 slice exists for a simulator to link against.
        ARCHS: 'arm64',
        ENABLE_BITCODE: 'NO',
        TARGETED_DEVICE_FAMILY: '1,2',
    };
    const targetCommon = {
        PRODUCT_NAME: '$(TARGET_NAME)',
        PRODUCT_BUNDLE_IDENTIFIER: o.bundleId,
        MARKETING_VERSION: o.version,
        CURRENT_PROJECT_VERSION: String(o.versionCode),
        INFOPLIST_FILE: 'App/Info.plist',
        GENERATE_INFOPLIST_FILE: 'NO',
        ASSETCATALOG_COMPILER_APPICON_NAME: 'AppIcon',
        CODE_SIGN_STYLE: 'Automatic',
        // The xcframework sits at the project root, next to the export's files.
        FRAMEWORK_SEARCH_PATHS: ['$(inherited)', '$(PROJECT_DIR)'],
        // -ObjC keeps the app delegate / view controller alive: they live in the
        // static library and nothing in main.m references them, so the linker
        // would otherwise drop those translation units.
        OTHER_LDFLAGS: ['$(inherited)', '-ObjC', '-lc++',
            ...SYSTEM_FRAMEWORKS.flatMap((f) => ['-framework', f])],
    };

    const out = [];
    const w = (line) => out.push(line);

    w('// !$*UTF8*$!');
    w('{');
    w('\tarchiveVersion = 1;');
    w('\tclasses = {');
    w('\t};');
    w('\tobjectVersion = 56;');
    w(`\trootObject = ${ids.project} /* Project object */;`);
    w('\tobjects = {');

    w('\n/* Begin PBXBuildFile section */');
    w(`\t\t${ids.buildMain} = {isa = PBXBuildFile; fileRef = ${ids.mainSource}; };`);
    w(`\t\t${ids.buildFramework} = {isa = PBXBuildFile; fileRef = ${ids.framework}; };`);
    for (const r of resources) {
        w(`\t\t${r.buildId} = {isa = PBXBuildFile; fileRef = ${r.fileId}; };`);
    }
    w('/* End PBXBuildFile section */');

    w('\n/* Begin PBXFileReference section */');
    w(`\t\t${ids.product} = {isa = PBXFileReference; explicitFileType = wrapper.application; `
        + `includeInIndex = 0; path = ${q(`${o.name}.app`)}; sourceTree = BUILT_PRODUCTS_DIR; };`);
    w(`\t\t${ids.mainSource} = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.objc; `
        + 'path = main.m; sourceTree = "<group>"; };');
    w(`\t\t${ids.infoPlist} = {isa = PBXFileReference; lastKnownFileType = text.plist.xml; `
        + 'path = Info.plist; sourceTree = "<group>"; };');
    w(`\t\t${ids.framework} = {isa = PBXFileReference; lastKnownFileType = wrapper.xcframework; `
        + `path = ${q(o.frameworkName)}; sourceTree = "<group>"; };`);
    for (const r of resources) {
        w(`\t\t${r.fileId} = {isa = PBXFileReference; lastKnownFileType = ${fileType(r.name, r.isDir)}; `
            + `path = ${q(r.name)}; sourceTree = "<group>"; };`);
    }
    w('/* End PBXFileReference section */');

    w('\n/* Begin PBXFrameworksBuildPhase section */');
    w(`\t\t${ids.frameworksPhase} = {`);
    w('\t\t\tisa = PBXFrameworksBuildPhase;');
    w('\t\t\tbuildActionMask = 2147483647;');
    w('\t\t\tfiles = (');
    w(`\t\t\t\t${ids.buildFramework},`);
    w('\t\t\t);');
    w('\t\t\trunOnlyForDeploymentPostprocessing = 0;');
    w('\t\t};');
    w('/* End PBXFrameworksBuildPhase section */');

    w('\n/* Begin PBXGroup section */');
    w(`\t\t${ids.mainGroup} = {`);
    w('\t\t\tisa = PBXGroup;');
    w('\t\t\tchildren = (');
    w(`\t\t\t\t${ids.appGroup} /* App */,`);
    w(`\t\t\t\t${ids.framework} /* ${o.frameworkName} */,`);
    for (const r of resources) w(`\t\t\t\t${r.fileId} /* ${r.name} */,`);
    w(`\t\t\t\t${ids.productsGroup} /* Products */,`);
    w('\t\t\t);');
    w('\t\t\tsourceTree = "<group>";');
    w('\t\t};');
    w(`\t\t${ids.appGroup} = {`);
    w('\t\t\tisa = PBXGroup;');
    w('\t\t\tchildren = (');
    w(`\t\t\t\t${ids.mainSource} /* main.m */,`);
    w(`\t\t\t\t${ids.infoPlist} /* Info.plist */,`);
    w('\t\t\t);');
    w('\t\t\tpath = App;');
    w('\t\t\tsourceTree = "<group>";');
    w('\t\t};');
    w(`\t\t${ids.productsGroup} = {`);
    w('\t\t\tisa = PBXGroup;');
    w('\t\t\tchildren = (');
    w(`\t\t\t\t${ids.product} /* ${o.name}.app */,`);
    w('\t\t\t);');
    w('\t\t\tname = Products;');
    w('\t\t\tsourceTree = "<group>";');
    w('\t\t};');
    w('/* End PBXGroup section */');

    w('\n/* Begin PBXNativeTarget section */');
    w(`\t\t${ids.target} = {`);
    w('\t\t\tisa = PBXNativeTarget;');
    w(`\t\t\tbuildConfigurationList = ${ids.targetConfigList};`);
    w('\t\t\tbuildPhases = (');
    w(`\t\t\t\t${ids.sourcesPhase},`);
    w(`\t\t\t\t${ids.frameworksPhase},`);
    w(`\t\t\t\t${ids.resourcesPhase},`);
    w('\t\t\t);');
    w('\t\t\tbuildRules = (');
    w('\t\t\t);');
    w('\t\t\tdependencies = (');
    w('\t\t\t);');
    w(`\t\t\tname = ${q(o.name)};`);
    w(`\t\t\tproductName = ${q(o.name)};`);
    w(`\t\t\tproductReference = ${ids.product};`);
    w('\t\t\tproductType = "com.apple.product-type.application";');
    w('\t\t};');
    w('/* End PBXNativeTarget section */');

    w('\n/* Begin PBXProject section */');
    w(`\t\t${ids.project} = {`);
    w('\t\t\tisa = PBXProject;');
    w('\t\t\tattributes = {');
    w('\t\t\t\tBuildIndependentTargetsInParallel = 1;');
    w('\t\t\t\tLastUpgradeCheck = 1600;');
    w('\t\t\t\tTargetAttributes = {');
    w(`\t\t\t\t\t${ids.target} = {`);
    w('\t\t\t\t\t\tCreatedOnToolsVersion = 16.0;');
    w('\t\t\t\t\t};');
    w('\t\t\t\t};');
    w('\t\t\t};');
    w(`\t\t\tbuildConfigurationList = ${ids.projectConfigList};`);
    w('\t\t\tcompatibilityVersion = "Xcode 14.0";');
    w('\t\t\tdevelopmentRegion = en;');
    w('\t\t\thasScannedForEncodings = 0;');
    w('\t\t\tknownRegions = (');
    w('\t\t\t\ten,');
    w('\t\t\t\tBase,');
    w('\t\t\t);');
    w(`\t\t\tmainGroup = ${ids.mainGroup};`);
    w(`\t\t\tproductRefGroup = ${ids.productsGroup};`);
    w('\t\t\tprojectDirPath = "";');
    w('\t\t\tprojectRoot = "";');
    w('\t\t\ttargets = (');
    w(`\t\t\t\t${ids.target},`);
    w('\t\t\t);');
    w('\t\t};');
    w('/* End PBXProject section */');

    w('\n/* Begin PBXResourcesBuildPhase section */');
    w(`\t\t${ids.resourcesPhase} = {`);
    w('\t\t\tisa = PBXResourcesBuildPhase;');
    w('\t\t\tbuildActionMask = 2147483647;');
    w('\t\t\tfiles = (');
    for (const r of resources) w(`\t\t\t\t${r.buildId} /* ${r.name} */,`);
    w('\t\t\t);');
    w('\t\t\trunOnlyForDeploymentPostprocessing = 0;');
    w('\t\t};');
    w('/* End PBXResourcesBuildPhase section */');

    w('\n/* Begin PBXSourcesBuildPhase section */');
    w(`\t\t${ids.sourcesPhase} = {`);
    w('\t\t\tisa = PBXSourcesBuildPhase;');
    w('\t\t\tbuildActionMask = 2147483647;');
    w('\t\t\tfiles = (');
    w(`\t\t\t\t${ids.buildMain},`);
    w('\t\t\t);');
    w('\t\t\trunOnlyForDeploymentPostprocessing = 0;');
    w('\t\t};');
    w('/* End PBXSourcesBuildPhase section */');

    w('\n/* Begin XCBuildConfiguration section */');
    const config = (id, name, settings) => {
        w(`\t\t${id} = {`);
        w('\t\t\tisa = XCBuildConfiguration;');
        w('\t\t\tbuildSettings = {');
        w(settingsBlock(settings, 4));
        w('\t\t\t};');
        w(`\t\t\tname = ${name};`);
        w('\t\t};');
    };
    config(ids.projectDebug, 'Debug', {
        ...projectCommon,
        DEBUG_INFORMATION_FORMAT: 'dwarf',
        ENABLE_TESTABILITY: 'YES',
        GCC_OPTIMIZATION_LEVEL: '0',
        GCC_PREPROCESSOR_DEFINITIONS: ['DEBUG=1', '$(inherited)'],
        MTL_ENABLE_DEBUG_INFO: 'INCLUDE_SOURCE',
        ONLY_ACTIVE_ARCH: 'YES',
    });
    config(ids.projectRelease, 'Release', {
        ...projectCommon,
        DEBUG_INFORMATION_FORMAT: 'dwarf-with-dsym',
        ENABLE_NS_ASSERTIONS: 'NO',
        MTL_ENABLE_DEBUG_INFO: 'NO',
        ONLY_ACTIVE_ARCH: 'NO',
        VALIDATE_PRODUCT: 'YES',
    });
    config(ids.targetDebug, 'Debug', targetCommon);
    config(ids.targetRelease, 'Release', targetCommon);
    w('/* End XCBuildConfiguration section */');

    w('\n/* Begin XCConfigurationList section */');
    const configList = (id, label, debug, release) => {
        w(`\t\t${id} /* Build configuration list for ${label} */ = {`);
        w('\t\t\tisa = XCConfigurationList;');
        w('\t\t\tbuildConfigurations = (');
        w(`\t\t\t\t${debug} /* Debug */,`);
        w(`\t\t\t\t${release} /* Release */,`);
        w('\t\t\t);');
        w('\t\t\tdefaultConfigurationIsVisible = 0;');
        w('\t\t\tdefaultConfigurationName = Release;');
        w('\t\t};');
    };
    configList(ids.projectConfigList, 'PBXProject', ids.projectDebug, ids.projectRelease);
    configList(ids.targetConfigList, 'PBXNativeTarget', ids.targetDebug, ids.targetRelease);
    w('/* End XCConfigurationList section */');

    w('\t};');
    w('}');
    return `${out.join('\n')}\n`;
}

/**
 * The shared scheme that makes the target runnable straight from a fresh open —
 * without one Xcode has to autocreate it, and `xcodebuild -scheme` finds nothing.
 *
 * Metal API Validation is off (`enableGPUValidationMode = "1"` — Xcode writes that
 * to mean DISABLED; enabled is the absent default). Dawn's Metal backend calls
 * `setDepthClipMode` unconditionally, and the iOS simulator's Metal does not
 * support depth clip mode at all, so the validation layer asserts on the first
 * frame — on a device it is fine, and with validation off the simulator renders
 * correctly too. A game developer writes no Metal, so the first Run should not
 * abort on a backend limitation they cannot act on. Re-enable it per project in
 * Edit Scheme → Run → Diagnostics.
 */
export function renderScheme(name) {
    const id = oid('target');
    return `<?xml version="1.0" encoding="UTF-8"?>
<Scheme LastUpgradeVersion = "1600" version = "1.7">
   <BuildAction parallelizeBuildables = "YES" buildImplicitDependencies = "YES">
      <BuildActionEntries>
         <BuildActionEntry buildForTesting = "YES" buildForRunning = "YES" buildForProfiling = "YES" buildForArchiving = "YES" buildForAnalyzing = "YES">
            <BuildableReference
               BuildableIdentifier = "primary"
               BlueprintIdentifier = "${id}"
               BuildableName = "${name}.app"
               BlueprintName = "${name}"
               ReferencedContainer = "container:${name}.xcodeproj">
            </BuildableReference>
         </BuildActionEntry>
      </BuildActionEntries>
   </BuildAction>
   <TestAction buildConfiguration = "Debug" selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB" selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB" shouldUseLaunchSchemeArgsEnv = "YES">
      <Testables>
      </Testables>
   </TestAction>
   <LaunchAction buildConfiguration = "Debug" selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB" selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB" launchStyle = "0" useCustomWorkingDirectory = "NO" ignoresPersistentStateOnLaunch = "NO" debugDocumentVersioning = "YES" debugServiceExtension = "internal" enableGPUValidationMode = "1" allowLocationSimulation = "YES">
      <BuildableProductRunnable runnableDebuggingMode = "0">
         <BuildableReference
            BuildableIdentifier = "primary"
            BlueprintIdentifier = "${id}"
            BuildableName = "${name}.app"
            BlueprintName = "${name}"
            ReferencedContainer = "container:${name}.xcodeproj">
         </BuildableReference>
      </BuildableProductRunnable>
   </LaunchAction>
   <ProfileAction buildConfiguration = "Release" shouldUseLaunchSchemeArgsEnv = "YES" savedToolIdentifier = "" useCustomWorkingDirectory = "NO" debugDocumentVersioning = "YES">
      <BuildableProductRunnable runnableDebuggingMode = "0">
         <BuildableReference
            BuildableIdentifier = "primary"
            BlueprintIdentifier = "${id}"
            BuildableName = "${name}.app"
            BlueprintName = "${name}"
            ReferencedContainer = "container:${name}.xcodeproj">
         </BuildableReference>
      </BuildableProductRunnable>
   </ProfileAction>
   <AnalyzeAction buildConfiguration = "Debug">
   </AnalyzeAction>
   <ArchiveAction buildConfiguration = "Release" revealArchiveInOrganizer = "YES">
   </ArchiveAction>
</Scheme>
`;
}