@cmpose/core 0.1.1 → 0.2.0

package/README.md

@@ -1,3 +1,5 @@
 # @cmpose/core
 
 The cmpose generator library: it turns the pinned Compose Multiplatform template into a new project (validation, package and name rewrites, optional features and modules). It is the same code cmpose.dev runs. See the README at the root of the cmpose repository for usage and development.
+
+It also generates Unity mobile games from the pinned game template: `game.validateGame`, `game.generateGame` and `game.describeGame`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cmpose/core",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "cmpose project generator core (Compose Multiplatform)",
   "license": "MIT",
   "repository": {
@@ -29,7 +29,8 @@
     "node": ">=20"
   },
   "scripts": {
-    "test": "node --test test/*.test.js"
+    "test": "node --test test/*.test.js",
+    "prepublishOnly": "node scripts/check-pins.js"
   },
   "dependencies": {
     "fs-extra": "^11.3.2"

package/src/game/buildScenes.js

@@ -0,0 +1,40 @@
+const path = require('path');
+const fs = require('fs-extra');
+
+// ProjectSettings/EditorBuildSettings.asset lists the scenes a build contains, three lines each:
+//   - enabled: 1
+//     path: Assets/…/Name.unity
+//     guid: <32 hex>
+// A flag that deletes a scene file must drop its entry too, or the build skips it and its guid dangles.
+const FILE = 'ProjectSettings/EditorBuildSettings.asset';
+const ENTRY = /^ {2}- enabled: [01]\r?\n {4}path: (.*?)\r?\n {4}guid: [0-9a-f]{32}\r?\n/gm;
+
+async function readSettings(projectDir) {
+    const file = path.join(projectDir, FILE);
+    return (await fs.pathExists(file)) ? { file, text: await fs.readFile(file, 'utf8') } : null;
+}
+
+async function pruneBuildScenes(projectDir) {
+    const settings = await readSettings(projectDir);
+    if (!settings) return [];
+    const dropped = [];
+    const next = settings.text.replace(ENTRY, (entry, scene) => {
+        if (fs.existsSync(path.join(projectDir, scene))) return entry;
+        dropped.push(scene);
+        return '';
+    });
+    if (dropped.length) await fs.writeFile(settings.file, next);
+    return dropped;
+}
+
+async function findMissingBuildScenes(projectDir) {
+    const settings = await readSettings(projectDir);
+    if (!settings) return [];
+    const problems = [];
+    for (const [, scene] of settings.text.matchAll(ENTRY)) {
+        if (!(await fs.pathExists(path.join(projectDir, scene)))) problems.push(`build scene missing: ${scene}`);
+    }
+    return problems;
+}
+
+module.exports = { pruneBuildScenes, findMissingBuildScenes };

package/src/game/contract.js

@@ -0,0 +1,40 @@
+'use strict';
+const { hashContract } = require('../contract');
+const limits = require('../limits');
+
+// The Unity game generator's contract: what the game_* tools accept. Published facts feed contractVersion.
+const GAME_SCHEMA = Object.freeze({
+    engine: 'unity',
+    unityVersion: '6000.3.25f1',
+    templateTypes: ['showcase', 'blank'],
+    renders: ['2d', '3d'],
+    flags: ['saveSystem', 'uiTheme', 'multiLang', 'network', 'networkInspector', 'purchases', 'ads', 'leaderboards'],
+    flagRequires: { networkInspector: ['network'] },
+    idGroups: {
+        admob: { flag: 'ads', fields: ['androidAppId', 'iosAppId', 'androidBanner', 'androidInterstitial', 'androidRewarded', 'iosBanner', 'iosInterstitial', 'iosRewarded'] },
+        revenueCat: { flag: 'purchases', fields: ['appleApiKey', 'googleApiKey'] },
+        gameServices: { flag: 'leaderboards', fields: ['androidAppId', 'leaderboardAndroid', 'firstCompletionAndroid', 'tenCompletionsAndroid', 'leaderboardIos', 'firstCompletionIos', 'tenCompletionsIos'] }
+    },
+    limits: { minSdkMin: 25, minSdkMax: 36, iosVersionMin: '15.0', maxModules: 3, nameMax: 30, appNameMax: 30, packageNameMax: 50, moduleNameMax: 20 },
+    reservedNames: ['UnityBase', 'Kturker'],
+    // Module names a copy of Sample cannot take: the template's own folders; names whose copy breaks C# binding
+    // (game: GameInstaller would call itself; action, i: VContainer's ActionInstaller/IInstaller; bonus, leaderboard:
+    // Sample's own BonusView/LeaderboardView); names whose namespace would hide a type the Sample code uses
+    // (Button, Lifetime, Object, ...); and the template's string-key prefixes (a duplicate key is dropped)
+    reservedModuleNames: ['sample', 'shell', 'showcase', 'build',
+        'game', 'action', 'i', 'bonus', 'leaderboard',
+        'button', 'lifetime', 'object', 'preserve', 'resources', 'serializable', 'transform',
+        'about', 'ads', 'boot', 'common', 'guide', 'inspector', 'leaderboards', 'menu', 'network', 'pause',
+        'purchases', 'runner2d', 'settings', 'theme', 'track3d', 'update'],
+    reservedPackagePrefix: 'com.kturker'
+});
+
+function gameContractFacts() {
+    return { ...GAME_SCHEMA, limits: { ...GAME_SCHEMA.limits, iosVersionMax: limits.iosVersionMax } };
+}
+
+function gameContractVersion() {
+    return hashContract(gameContractFacts());
+}
+
+module.exports = { GAME_SCHEMA, gameContractFacts, gameContractVersion };

package/src/game/describe.js

@@ -0,0 +1,25 @@
+'use strict';
+const pins = require('../pins');
+const { GAME_SCHEMA, gameContractFacts, gameContractVersion } = require('./contract');
+
+/** What the Unity game generator offers: engine, pinned template, defaults and the contract facts */
+function describeGame() {
+    return {
+        engine: GAME_SCHEMA.engine,
+        unityVersion: GAME_SCHEMA.unityVersion,
+        contractVersion: gameContractVersion(),
+        template: pins.game,
+        defaults: {
+            templateType: 'showcase',
+            render: '2d',
+            flags: { showcase: GAME_SCHEMA.flags.slice(), blank: [] },
+            features: [],
+            minSdk: GAME_SCHEMA.limits.minSdkMin,
+            iosVersion: GAME_SCHEMA.limits.iosVersionMin,
+            ci: false
+        },
+        contract: gameContractFacts()
+    };
+}
+
+module.exports = { describeGame };

package/src/game/flags.js

@@ -0,0 +1,314 @@
+const path = require('path');
+const fs = require('fs-extra');
+const { removeLineMarkedBlock, stripLineMarkers } = require('./markers');
+const { removePackagesInProject } = require('./packages');
+const { getDefines, setDefines } = require('./projectSettings');
+const { readMetaGuid } = require('./guid');
+const { findResidue } = require('./residue');
+const { pruneBuildScenes } = require('./buildScenes');
+
+// cmpose.dev/game: a feature flag is folders + marked C# blocks ('// cmpose:<flag>' … '// /cmpose:<flag>') +
+// asmdef references + packages + a scripting define, all listed in the template's .cmpose/flags.json. A flag may
+// require others ("requires"); turning one off turns off the flags that require it. A render
+// other than the upstream one is an overlay under .cmpose/layers/ whose files replace the project's (same guids).
+// Turning flags off and picking the render only edits files; Unity never runs here.
+// Internal flags (Faz 2f: sample, showcase and its games) are never turned off by name: a project kind does it
+// ("kinds": blank turns the showcase off, showcase turns the sample off and keeps the render's game). Scenes whose
+// file a flag removes are dropped from Build Settings.
+const MANIFEST = '.cmpose/flags.json';
+const LAYERS = '.cmpose/layers';
+const DEFINE_TARGETS = ['Android', 'iPhone'];
+const SYMBOL = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const FLAG_NAME = /^[A-Za-z][A-Za-z0-9]*$/;
+const RENDER_NAME = /^[a-z0-9]+$/;
+const KIND_NAME = /^[a-z]+$/;
+// Files only the upstream repo or Unity's local state carry; never scanned for residue
+const RESIDUE_IGNORE = ['README.md', 'MAINTAINING.md', 'tools/', 'Builds/', 'Assets/Editor/Maintainer/', '.cmpose/'];
+
+const isObject = (v) => v && typeof v === 'object' && !Array.isArray(v);
+
+function safeRel(p, what) {
+    if (typeof p !== 'string' || !p || path.isAbsolute(p) || p.split(/[\\/]/).includes('..')) {
+        throw new Error(`${MANIFEST}: ${what}: '${p}' must be a relative path inside the project`);
+    }
+    return p;
+}
+
+function nameList(value, what) {
+    if (value === undefined) return [];
+    if (!Array.isArray(value) || value.some((v) => typeof v !== 'string' || !v)) {
+        throw new Error(`${MANIFEST}: ${what} must be a list of names`);
+    }
+    return [...value];
+}
+
+function readInternal(value, name) {
+    if (value === undefined) return false;
+    if (typeof value !== 'boolean') throw new Error(`${MANIFEST}: flag ${name} "internal" must be true or false`);
+    return value;
+}
+
+// A manifest from before Faz 2f has no "kinds": it only knows blank, which turns nothing off
+function parseKinds(value, flags, renders) {
+    if (value === undefined) return { blank: { off: [], games: {} } };
+    if (!isObject(value) || !isObject(value.blank)) throw new Error(`${MANIFEST}: "kinds" needs a "blank" kind`);
+    const kinds = {};
+    for (const [name, kind] of Object.entries(value)) {
+        if (!KIND_NAME.test(name)) throw new Error(`${MANIFEST}: '${name}' is not a valid kind name`);
+        if (!isObject(kind)) throw new Error(`${MANIFEST}: kind ${name} must be an object`);
+        const off = nameList(kind.off, `kind ${name} off`);
+        for (const flag of off) {
+            if (!flags[flag]) throw new Error(`${MANIFEST}: kind ${name} turns off unknown flag ${flag}`);
+            if (!flags[flag].internal) throw new Error(`${MANIFEST}: kind ${name} turns off ${flag}, which is not internal`);
+        }
+        const games = {};
+        if (kind.games !== undefined) {
+            if (!isObject(kind.games)) throw new Error(`${MANIFEST}: kind ${name} games must map renders to flags`);
+            for (const [render, game] of Object.entries(kind.games)) {
+                if (!Object.prototype.hasOwnProperty.call(renders, render)) {
+                    throw new Error(`${MANIFEST}: kind ${name} has a game for unknown render ${render}`);
+                }
+                if (!flags[game] || !flags[game].internal) {
+                    throw new Error(`${MANIFEST}: kind ${name} game ${game} must be an internal flag`);
+                }
+                games[render] = game;
+            }
+        }
+        kinds[name] = { off, games };
+    }
+    return kinds;
+}
+
+function parseFlagManifest(text) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    } catch (error) {
+        throw new Error(`${MANIFEST}: ${error.message}`);
+    }
+    if (!isObject(raw) || !isObject(raw.flags) || !isObject(raw.renders)) {
+        throw new Error(`${MANIFEST}: needs "flags" and "renders" objects`);
+    }
+    const flags = {};
+    for (const [name, flag] of Object.entries(raw.flags)) {
+        if (!FLAG_NAME.test(name)) throw new Error(`${MANIFEST}: '${name}' is not a valid flag name`);
+        if (!isObject(flag) || !SYMBOL.test(flag.define || '')) throw new Error(`${MANIFEST}: flag ${name} needs a valid "define"`);
+        flags[name] = {
+            define: flag.define,
+            paths: nameList(flag.paths, `flag ${name} paths`).map((p) => safeRel(p, `flag ${name}`)),
+            asmdefs: nameList(flag.asmdefs, `flag ${name} asmdefs`),
+            packages: nameList(flag.packages, `flag ${name} packages`),
+            requires: nameList(flag.requires, `flag ${name} requires`),
+            internal: readInternal(flag.internal, name)
+        };
+    }
+    for (const [name, flag] of Object.entries(flags)) {
+        for (const required of flag.requires) {
+            if (!flags[required]) throw new Error(`${MANIFEST}: flag ${name} requires unknown flag ${required}`);
+        }
+    }
+    const renders = {};
+    for (const [name, dir] of Object.entries(raw.renders)) {
+        if (!RENDER_NAME.test(name)) throw new Error(`${MANIFEST}: '${name}' is not a valid render name`);
+        renders[name] = dir === null ? null : safeRel(dir, `render ${name}`);
+    }
+    if (Object.values(renders).filter((d) => d === null).length !== 1) {
+        throw new Error(`${MANIFEST}: exactly one render must be the upstream one (null)`);
+    }
+    return { flags, renders, kinds: parseKinds(raw.kinds, flags, renders) };
+}
+
+async function readFlagManifest(projectDir) {
+    const file = path.join(projectDir, MANIFEST);
+    if (!(await fs.pathExists(file))) throw new Error(`${MANIFEST} not found in ${projectDir}`);
+    return parseFlagManifest(await fs.readFile(file, 'utf8'));
+}
+
+// Every file under dir (relative, '/'-separated, sorted); with extensions, only those
+async function listFiles(dir, extensions) {
+    const out = [];
+    async function walk(abs, rel) {
+        const entries = (await fs.readdir(abs, { withFileTypes: true })).sort((a, b) => (a.name < b.name ? -1 : 1));
+        for (const entry of entries) {
+            const r = rel ? `${rel}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) await walk(path.join(abs, entry.name), r);
+            else if (!extensions || extensions.has(path.extname(entry.name))) out.push(r);
+        }
+    }
+    if (await fs.pathExists(dir)) await walk(dir, '');
+    return out;
+}
+
+async function checkRenderLayers(projectDir, manifest) {
+    const problems = [];
+    for (const [name, rel] of Object.entries(manifest.renders)) {
+        if (rel === null) continue;
+        const layer = path.join(projectDir, rel);
+        const files = await listFiles(layer);
+        if (files.length === 0) {
+            problems.push(`render ${name}: ${rel} is missing or empty`);
+            continue;
+        }
+        for (const file of files) {
+            const target = path.join(projectDir, file);
+            const targetExists = await fs.pathExists(target);
+            if (!file.endsWith('.meta')) {
+                if (!files.includes(`${file}.meta`)) problems.push(`render ${name}: ${file} has no .meta`);
+                if (!targetExists) problems.push(`render ${name}: ${file} replaces nothing`);
+                continue;
+            }
+            if (!targetExists) {
+                problems.push(`render ${name}: ${file} replaces nothing`);
+                continue;
+            }
+            let own;
+            let theirs;
+            try {
+                own = readMetaGuid(await fs.readFile(path.join(layer, file), 'utf8'));
+                theirs = readMetaGuid(await fs.readFile(target, 'utf8'));
+            } catch (error) {
+                problems.push(`render ${name}: ${file}: ${error.message}`);
+                continue;
+            }
+            if (own !== theirs) problems.push(`render ${name}: ${file} guid ${own} differs from the project's ${theirs}`);
+        }
+    }
+    return problems.sort();
+}
+
+// A flag that requires a turned-off flag goes off with it (networkInspector without network), chains included
+function withRequirers(manifest, off) {
+    const out = [...new Set(off)];
+    let grown = true;
+    while (grown) {
+        grown = false;
+        for (const [name, flag] of Object.entries(manifest.flags)) {
+            if (!out.includes(name) && flag.requires.some((r) => out.includes(r))) {
+                out.push(name);
+                grown = true;
+            }
+        }
+    }
+    return out;
+}
+
+function resolveOptions(manifest, { kind = 'blank', off = [], render } = {}) {
+    const chosenKind = manifest.kinds[kind];
+    if (!chosenKind) throw new Error(`unknown kind: ${kind}`);
+    for (const flag of off) {
+        if (!manifest.flags[flag]) throw new Error(`unknown flag: ${flag}`);
+        if (manifest.flags[flag].internal) throw new Error(`flag ${flag} is internal: pick a kind instead`);
+    }
+    const upstream = Object.keys(manifest.renders).find((r) => manifest.renders[r] === null);
+    const chosen = render === undefined ? upstream : render;
+    if (!Object.prototype.hasOwnProperty.call(manifest.renders, chosen)) throw new Error(`unknown render: ${chosen}`);
+    const games = Object.values(chosenKind.games);
+    if (games.length && !chosenKind.games[chosen]) throw new Error(`${kind} has no game for render ${chosen}`);
+    const otherGames = games.filter((g) => g !== chosenKind.games[chosen]);
+    return { off: withRequirers(manifest, [...off, ...chosenKind.off, ...otherGames]), render: chosen };
+}
+
+async function applyFlags(projectDir, options = {}) {
+    const manifest = await readFlagManifest(projectDir);
+    const { off, render } = resolveOptions(manifest, options);
+    const offSet = new Set(off);
+    const on = Object.keys(manifest.flags).filter((f) => !offSet.has(f));
+
+    const layerProblems = await checkRenderLayers(projectDir, manifest);
+    if (layerProblems.length) throw new Error(`render layers: ${layerProblems.join('; ')}`);
+    if (manifest.renders[render] !== null) {
+        await fs.copy(path.join(projectDir, manifest.renders[render]), projectDir, { overwrite: true });
+    }
+
+    // Every path is checked before anything is removed, so a path inside another turned-off flag's folder (multiLang's
+    // tables inside network's folder) is simply gone by its turn; a path missing from the template still fails
+    const removals = off.flatMap((flag) => manifest.flags[flag].paths.map((rel) => ({ flag, rel })));
+    for (const { flag, rel } of removals) {
+        if (!(await fs.pathExists(path.join(projectDir, rel)))) throw new Error(`${flag}: path not found: ${rel}`);
+    }
+    for (const { rel } of removals) {
+        const abs = path.join(projectDir, rel);
+        await fs.remove(abs);
+        await fs.remove(`${abs}.meta`);
+    }
+    await pruneBuildScenes(projectDir);
+
+    for (const rel of await listFiles(path.join(projectDir, 'Assets'), new Set(['.cs']))) {
+        const abs = path.join(projectDir, 'Assets', rel);
+        const before = await fs.readFile(abs, 'utf8');
+        let text = before;
+        try {
+            for (const flag of off) text = removeLineMarkedBlock(text, flag);
+            for (const flag of on) text = stripLineMarkers(text, flag);
+        } catch (error) {
+            throw new Error(`Assets/${rel}: ${error.message}`);
+        }
+        if (text !== before) await fs.writeFile(abs, text);
+    }
+
+    const dropped = new Set(off.flatMap((f) => manifest.flags[f].asmdefs));
+    for (const rel of await listFiles(path.join(projectDir, 'Assets'), new Set(['.asmdef']))) {
+        const abs = path.join(projectDir, 'Assets', rel);
+        const asmdef = JSON.parse(await fs.readFile(abs, 'utf8'));
+        if (!Array.isArray(asmdef.references)) continue;
+        const kept = asmdef.references.filter((r) => !dropped.has(r));
+        if (kept.length === asmdef.references.length) continue;
+        asmdef.references = kept;
+        await fs.writeFile(abs, `${JSON.stringify(asmdef, null, 4)}\n`);
+    }
+
+    if (off.length) {
+        const settingsPath = path.join(projectDir, 'ProjectSettings', 'ProjectSettings.asset');
+        let settings = await fs.readFile(settingsPath, 'utf8');
+        const drop = new Set(off.map((f) => manifest.flags[f].define));
+        for (const target of DEFINE_TARGETS) {
+            const current = getDefines(settings, target);
+            for (const flag of off) {
+                const define = manifest.flags[flag].define;
+                if (!current.includes(define)) throw new Error(`${flag}: define ${define} missing for ${target}`);
+            }
+            settings = setDefines(settings, target, current.filter((d) => !drop.has(d)));
+        }
+        await fs.writeFile(settingsPath, settings);
+    }
+
+    const keep = new Set(on.flatMap((f) => manifest.flags[f].packages));
+    const removedPackages = [...new Set(off.flatMap((f) => manifest.flags[f].packages))].filter((p) => !keep.has(p));
+    if (removedPackages.length) await removePackagesInProject(projectDir, removedPackages);
+
+    await fs.remove(path.join(projectDir, MANIFEST));
+    await fs.remove(path.join(projectDir, LAYERS));
+    return { off, render, removedPackages };
+}
+
+// What a turned-off flag must not leave behind: its define, its assembly names (which also cover 'using'
+// lines, namespaces being the assembly names) and, for every flag, the markers themselves
+async function findFlagResidue(projectDir, manifest, off) {
+    const rules = off.map((flag) => ({
+        name: `flag ${flag}:`,
+        tokens: [manifest.flags[flag].define, ...manifest.flags[flag].asmdefs]
+    }));
+    rules.push({ name: 'marker', tokens: Object.keys(manifest.flags).map((f) => `cmpose:${f}`), extensions: ['.cs'] });
+    return findResidue(projectDir, rules, { ignore: RESIDUE_IGNORE });
+}
+
+function flagVariants(manifest) {
+    const flags = Object.keys(manifest.flags).filter((f) => !manifest.flags[f].internal);
+    const overlays = Object.keys(manifest.renders).filter((r) => manifest.renders[r] !== null);
+    const variants = flags.map((f) => ({ name: `no-${f}`, off: [f], render: undefined, kind: 'blank' }));
+    for (const r of overlays) variants.push({ name: `render-${r}`, off: [], render: r, kind: 'blank' });
+    if (flags.length) {
+        const r = overlays[0];
+        variants.push({ name: r ? `all-off-${r}` : 'all-off', off: flags, render: r, kind: 'blank' });
+    }
+    const showcase = manifest.kinds.showcase;
+    for (const render of Object.keys(showcase ? showcase.games : {})) {
+        variants.push({ name: `showcase-${render}`, off: [], render, kind: 'showcase' });
+        variants.push({ name: `showcase-all-off-${render}`, off: flags, render, kind: 'showcase' });
+    }
+    return variants;
+}
+
+module.exports = {
+    MANIFEST, LAYERS, parseFlagManifest, readFlagManifest, checkRenderLayers, applyFlags, findFlagResidue, flagVariants
+};

package/src/game/generate.js

@@ -0,0 +1,86 @@
+'use strict';
+const fs = require('fs-extra');
+const path = require('path');
+const { log } = require('../log');
+const pins = require('../pins');
+const { applyCiOption } = require('../ciOption');
+const { COMMIT_FILE_NAME, REF_FILE_NAME } = require('../templateVersions');
+const { GAME_SCHEMA } = require('./contract');
+const { cloneModules } = require('./modules');
+const { applyFlags } = require('./flags');
+const { applyGameIdentity } = require('./identity');
+const { writeGameIds } = require('./ids');
+const { applyGameReadme } = require('./readme');
+const { buildGameRecord, writeGameRecord } = require('./record');
+const { verifyGameProject } = require('./verifier');
+
+// The template cache's own records and Unity's local state never reach the project; nor does the template's
+// LICENSE (the generated project is the user's, to license as they choose)
+const LEFTOVERS = ['.git', COMMIT_FILE_NAME, REF_FILE_NAME, 'LICENSE', 'Library', 'Temp', 'Logs', 'UserSettings'];
+const PACKAGE_GUIDS = path.join('.cmpose', 'package-guids.txt');
+
+function gameWarnings(value) {
+    const on = (flag) => value.flags.includes(flag);
+    const warnings = [];
+    if (on('ads') && !value.ids.admob) warnings.push('Ads use AdMob test IDs: replace them with your own before release.');
+    if (on('purchases') && !value.ids.revenueCat) warnings.push('Purchases use the RevenueCat Test Store key: replace it before release.');
+    if (on('leaderboards') && !value.ids.gameServices) {
+        warnings.push('Leaderboard and achievement IDs are placeholders: game services stay off until you set them.');
+    }
+    warnings.push(`Open the project with Unity ${GAME_SCHEMA.unityVersion} (Android and iOS Build Support); the first import takes a few minutes.`);
+    return warnings;
+}
+
+// Turns a fresh Unity template copy (projectDir) into the requested game, in place.
+// value: validateGame().value. generatorVersion: who ran the core, for the record (e.g. mcp@0.2.0). template: { repo, ref, commit } for the record; without it the pinned repo and the
+// cache's markers are recorded. Throws when a step fails or the result fails verification.
+async function generateGame(value, { projectDir, template = null, coreVersion, generatorVersion = null, now = new Date() }) {
+    const readMarker = (name) => fs.readFile(path.join(projectDir, name), 'utf8').then((v) => v.trim() || null, () => null);
+    const source = template || {
+        repo: pins.game.repo,
+        ref: (await readMarker(REF_FILE_NAME)) || pins.game.ref,
+        commit: await readMarker(COMMIT_FILE_NAME)
+    };
+
+    // 1. leftovers
+    for (const leftover of LEFTOVERS) await fs.remove(path.join(projectDir, leftover));
+    log.info('✅ Cleanup completed');
+
+    // 2. blank modules, cloned before the flags so a turned-off flag removes their parts too
+    if (value.templateType === 'blank' && value.features.length) {
+        await cloneModules(projectDir, value.features, { seed: value.packageName });
+        log.info(`✅ Added modules: ${value.features.join(', ')}`);
+    }
+
+    // 3. flags and render (showcase keeps every flag)
+    const off = GAME_SCHEMA.flags.filter((f) => !value.flags.includes(f));
+    await applyFlags(projectDir, { kind: value.templateType, render: value.render, off });
+    log.info(`✅ Applied ${value.templateType} (${value.render}), flags off: ${off.length ? off.join(', ') : 'none'}`);
+
+    // 4–6. identity, real IDs, CI and README
+    await applyGameIdentity(projectDir, value);
+    await writeGameIds(projectDir, value.ids);
+    await applyCiOption(projectDir, value.ci);
+    await applyGameReadme(projectDir, value);
+    log.info(`✅ Renamed to ${value.companyName}.${value.projectName} (${value.packageName})`);
+
+    // 7. a broken project is never returned
+    const problems = await verifyGameProject(projectDir);
+    if (problems.length) throw new Error('generated project failed verification:\n- ' + problems.join('\n- '));
+
+    // 8. the template's package guid allowlist goes; the record stays
+    await fs.remove(path.join(projectDir, PACKAGE_GUIDS));
+    const record = buildGameRecord({ template: source, coreVersion, generatorVersion, value, now });
+    await writeGameRecord(projectDir, record);
+
+    return {
+        templateType: value.templateType,
+        render: value.render,
+        flags: value.flags.slice(),
+        features: value.features.slice(),
+        ids: record.ids,
+        warnings: gameWarnings(value)
+    };
+}
+
+module.exports = { generateGame, gameWarnings };

package/src/game/guid.js

@@ -0,0 +1,71 @@
+const crypto = require('crypto');
+const path = require('path');
+const fs = require('fs-extra');
+const { escapeRe } = require('./unityYaml');
+
+// Unity asset identity: every asset's .meta carries 'guid: <32 lowercase hex>'; scenes, prefabs and assets
+// point at it ('guid: <hex>'), asmdefs may too ('GUID:<hex>'). A cloned folder gets new guids, derived from
+// a seed so the same request always produces the same project.
+const GUID_RE = /^[0-9a-f]{32}$/;
+const TEXT_EXTENSIONS = new Set(['.meta', '.unity', '.prefab', '.asset', '.mat', '.asmdef', '.asmref', '.cs',
+    '.controller', '.anim', '.json', '.txt']);
+
+function newGuid(seed, oldGuid, name) {
+    return crypto.createHash('md5').update(`${seed}:${oldGuid}:${name}`).digest('hex');
+}
+
+function readMetaGuid(metaText) {
+    const m = /^guid: ([0-9a-f]{32})\r?$/m.exec(metaText);
+    if (!m) throw new Error('the .meta file has no valid guid line');
+    return m[1];
+}
+
+function remapGuids(text, map) {
+    return text.replace(/(guid: |GUID:)([0-9a-f]{32})(?![0-9a-f])/g,
+        (match, prefix, guid) => (map.has(guid) ? prefix + map.get(guid) : match));
+}
+
+// One pass, longest 'from' first, so a replacement is never replaced again
+function renamer(pairs) {
+    if (!pairs.length) return (s) => s;
+    const sorted = [...pairs].sort((a, b) => b.from.length - a.from.length);
+    const lookup = new Map(sorted.map((p) => [p.from, p.to]));
+    const re = new RegExp(sorted.map((p) => escapeRe(p.from)).join('|'), 'g');
+    return (s) => s.replace(re, (m) => lookup.get(m));
+}
+
+async function walk(dir) {
+    const out = [];
+    for (const entry of (await fs.readdir(dir, { withFileTypes: true })).sort((a, b) => (a.name < b.name ? -1 : 1))) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) out.push(...await walk(full));
+        else out.push(full);
+    }
+    return out;
+}
+
+async function cloneWithNewGuids(srcDir, dstDir, { seed, rename = [] }) {
+    if (await fs.pathExists(dstDir)) throw new Error(`destination exists: ${dstDir}`);
+    const apply = renamer(rename);
+    // The folder's own .meta sits next to it
+    const sources = await walk(srcDir);
+    const jobs = sources.map((file) => ({ from: file, to: path.join(dstDir, apply(path.relative(srcDir, file))) }));
+    if (await fs.pathExists(`${srcDir}.meta`)) jobs.push({ from: `${srcDir}.meta`, to: `${dstDir}.meta` });
+
+    const map = new Map();
+    for (const job of jobs.filter((j) => j.from.endsWith('.meta'))) {
+        const old = readMetaGuid(await fs.readFile(job.from, 'utf8'));
+        const name = path.relative(path.dirname(dstDir), job.to).split(path.sep).join('/');
+        map.set(old, newGuid(seed, old, name));
+    }
+    for (const job of jobs) {
+        if (TEXT_EXTENSIONS.has(path.extname(job.from))) {
+            await fs.outputFile(job.to, remapGuids(apply(await fs.readFile(job.from, 'utf8')), map));
+        } else {
+            await fs.copy(job.from, job.to);
+        }
+    }
+    return { map };
+}
+
+module.exports = { GUID_RE, newGuid, readMetaGuid, remapGuids, cloneWithNewGuids };