@cmpose/core 0.1.1 → 0.2.1

package/src/game/guidIntegrity.js

@@ -0,0 +1,81 @@
+const path = require('path');
+const fs = require('fs-extra');
+const { readMetaGuid } = require('./guid');
+
+// Unity's own resources (default font, built-in materials) are referenced with these guids
+const BUILTIN_GUIDS = ['0000000000000000e000000000000000', '0000000000000000f000000000000000'];
+// Serialized YAML that may point at other assets
+const YAML_EXTENSIONS = new Set(['.unity', '.prefab', '.asset', '.mat', '.controller', '.anim', '.asmdef', '.asmref', '.meta']);
+
+// Unity skips hidden files/folders and anything ending in '~'
+function ignoredByUnity(name) {
+    return name.startsWith('.') || name.endsWith('~');
+}
+
+// Folders Unity imports as a single plugin asset: one .meta for the folder, nothing inside is imported
+const FOLDER_ASSET_EXTENSIONS = new Set(['.androidlib', '.bundle', '.framework', '.xcframework', '.plugin']);
+
+async function walk(abs, rel, out) {
+    const entries = (await fs.readdir(abs, { withFileTypes: true })).sort((a, b) => (a.name < b.name ? -1 : 1));
+    for (const entry of entries) {
+        if (ignoredByUnity(entry.name)) continue;
+        const r = `${rel}/${entry.name}`;
+        out.push({ rel: r, dir: entry.isDirectory() });
+        if (entry.isDirectory() && !FOLDER_ASSET_EXTENSIONS.has(path.extname(entry.name))) await walk(path.join(abs, entry.name), r, out);
+    }
+}
+
+async function checkGuidIntegrity(dir, { allowlist = [], roots = ['Assets'] } = {}) {
+    const entries = [];
+    for (const root of roots) {
+        if (await fs.pathExists(path.join(dir, root))) await walk(path.join(dir, root), root, entries);
+    }
+    const present = new Set(entries.map((e) => e.rel));
+    const problems = [];
+    const owners = new Map();
+
+    for (const e of entries.filter((x) => !x.dir)) {
+        if (!e.rel.endsWith('.meta')) continue;
+        if (!present.has(e.rel.slice(0, -'.meta'.length))) problems.push(`orphan-meta ${e.rel}`);
+        let guid;
+        try {
+            guid = readMetaGuid(await fs.readFile(path.join(dir, e.rel), 'utf8'));
+        } catch (error) {
+            problems.push(`invalid-meta ${e.rel}`);
+            continue;
+        }
+        owners.set(guid, [...(owners.get(guid) || []), e.rel]);
+    }
+    for (const e of entries) {
+        if (!e.rel.endsWith('.meta') && !present.has(`${e.rel}.meta`)) problems.push(`missing-meta ${e.rel}`);
+    }
+    for (const [guid, paths] of owners) {
+        if (paths.length > 1) problems.push(`duplicate-guid ${guid}: ${[...paths].sort().join(', ')}`);
+    }
+
+    const known = new Set([...owners.keys(), ...BUILTIN_GUIDS, ...allowlist]);
+    for (const e of entries.filter((x) => !x.dir && YAML_EXTENSIONS.has(path.extname(x.rel)))) {
+        let text = await fs.readFile(path.join(dir, e.rel), 'utf8');
+        // A .meta's own 'guid:' line defines the asset; only the rest are references
+        if (e.rel.endsWith('.meta')) text = text.replace(/^guid: [0-9a-f]{32}\r?$/m, '');
+        for (const m of text.matchAll(/(?:guid: |GUID:)([0-9a-f]{32})(?![0-9a-f])/g)) {
+            if (!known.has(m[1])) problems.push(`dangling-guid ${m[1]} in ${e.rel}`);
+        }
+    }
+    return [...new Set(problems)].sort();
+}
+
+// The template's .cmpose/package-guids.txt: guids of assets inside packages, which template assets may reference
+async function readGuidAllowlist(file) {
+    if (!(await fs.pathExists(file))) return [];
+    const guids = [];
+    (await fs.readFile(file, 'utf8')).split('\n').forEach((raw, i) => {
+        const line = raw.trim();
+        if (!line || line.startsWith('#')) return;
+        if (!/^[0-9a-f]{32}$/.test(line)) throw new Error(`invalid guid on line ${i + 1} of ${file}`);
+        guids.push(line);
+    });
+    return guids;
+}
+
+module.exports = { BUILTIN_GUIDS, checkGuidIntegrity, readGuidAllowlist };

package/src/game/identity.js

@@ -0,0 +1,78 @@
+const path = require('path');
+const fs = require('fs-extra');
+const { escapeRe, getMapKeys, setMapEntry } = require('./unityYaml');
+const { PLAYER, applyIdentity } = require('./projectSettings');
+
+const TEXT_EXTENSIONS = new Set(['.cs', '.asmdef', '.asmref', '.prefab', '.unity', '.asset', '.mat', '.json', '.md', '.txt',
+    '.xml', '.ruleset', '.yml', '.uss', '.uxml']);
+const SKIPPED = new Set(['Library', 'Temp', 'Logs', 'UserSettings', '.git', '.cmpose']);
+const TEMPLATE_NAMESPACE = 'Kturker.UnityBase';
+
+// One pass, longest 'from' first, so a replacement is never replaced again
+function renamer(pairs) {
+    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));
+}
+
+// Every file and folder below dir outside the skipped top-level folders; folders are listed too
+async function walk(abs, rel, out) {
+    for (const entry of await fs.readdir(abs, { withFileTypes: true })) {
+        if (!rel && SKIPPED.has(entry.name)) continue;
+        if (entry.name === '.git') continue;
+        const r = rel ? `${rel}/${entry.name}` : entry.name;
+        out.push({ rel: r, dir: entry.isDirectory() });
+        if (entry.isDirectory()) await walk(path.join(abs, entry.name), r, out);
+    }
+}
+
+async function applyGameIdentity(projectDir, { companyName, projectName, appName, packageName, minSdk, iosVersion }) {
+    const rename = renamer([
+        { from: TEMPLATE_NAMESPACE, to: `${companyName}.${projectName}` },
+        { from: 'UnityBase', to: projectName },
+        { from: 'unitybase', to: projectName.toLowerCase() }
+    ]);
+    const entries = [];
+    await walk(projectDir, '', entries);
+
+    // 1. content
+    for (const e of entries) {
+        if (e.dir || !TEXT_EXTENSIONS.has(path.extname(e.rel))) continue;
+        const file = path.join(projectDir, e.rel);
+        const text = await fs.readFile(file, 'utf8');
+        const next = rename(text);
+        if (next !== text) await fs.writeFile(file, next);
+    }
+
+    // 2. names, deepest first; a .meta carries the template namespace in its name too, so it follows its asset
+    const namePart = renamer([{ from: TEMPLATE_NAMESPACE, to: `${companyName}.${projectName}` }]);
+    let renamedFiles = 0;
+    const named = entries.filter((e) => path.posix.basename(e.rel).includes(TEMPLATE_NAMESPACE))
+        .sort((a, b) => b.rel.split('/').length - a.rel.split('/').length);
+    for (const e of named) {
+        const from = path.join(projectDir, e.rel);
+        const to = path.join(path.dirname(from), namePart(path.basename(from)));
+        if (await fs.pathExists(to)) throw new Error(`cannot rename ${e.rel}: target exists`);
+        await fs.move(from, to);
+        renamedFiles += 1;
+    }
+
+    // 3. PlayerSettings
+    const settingsFile = path.join(projectDir, 'ProjectSettings', 'ProjectSettings.asset');
+    const settings = await fs.readFile(settingsFile, 'utf8');
+    let identified = applyIdentity(settings, {
+        companyName, productName: appName, bundleId: packageName, version: '1.0.0',
+        androidMinSdk: minSdk, iosTarget: iosVersion, urlScheme: projectName.toLowerCase()
+    });
+    // applyIdentity sets Android and iPhone; any other platform the template lists (Standalone …) gets the package too
+    for (const platform of getMapKeys(identified, 'applicationIdentifier', { doc: PLAYER })) {
+        if (platform !== 'Android' && platform !== 'iPhone') {
+            identified = setMapEntry(identified, 'applicationIdentifier', platform, packageName, { doc: PLAYER });
+        }
+    }
+    await fs.writeFile(settingsFile, identified);
+    return { renamedFiles };
+}
+
+module.exports = { applyGameIdentity };

package/src/game/ids.js

@@ -0,0 +1,88 @@
+const path = require('path');
+const fs = require('fs-extra');
+
+// Where each id group lands in the Unity template. `keys` maps the line's key to the field of the group.
+// kind 'cs': `public const string <Key> = "<value>";`, 'yaml': `  <key>: <value>`, 'xml': the games_app_id string.
+const ID_TARGETS = Object.freeze({
+    admob: [
+        {
+            file: 'Assets/_Project/Core/Ads/AdsConfig.cs',
+            kind: 'cs',
+            keys: {
+                BannerAndroid: 'androidBanner', InterstitialAndroid: 'androidInterstitial', RewardedAndroid: 'androidRewarded',
+                BannerIos: 'iosBanner', InterstitialIos: 'iosInterstitial', RewardedIos: 'iosRewarded'
+            }
+        },
+        {
+            file: 'Assets/GoogleMobileAds/Resources/GoogleMobileAdsSettings.asset',
+            kind: 'yaml',
+            keys: { adMobAndroidAppId: 'androidAppId', adMobIOSAppId: 'iosAppId' }
+        }
+    ],
+    revenueCat: [
+        {
+            file: 'Assets/_Project/Core/Purchases/PurchasesConfig.cs',
+            kind: 'cs',
+            keys: { ApiKeyApple: 'appleApiKey', ApiKeyGoogle: 'googleApiKey' }
+        }
+    ],
+    gameServices: [
+        {
+            file: 'Assets/_Project/Core/Leaderboards/LeaderboardsConfig.cs',
+            kind: 'cs',
+            keys: {
+                LeaderboardAndroid: 'leaderboardAndroid', FirstCompletionAndroid: 'firstCompletionAndroid',
+                TenCompletionsAndroid: 'tenCompletionsAndroid', LeaderboardIos: 'leaderboardIos',
+                FirstCompletionIos: 'firstCompletionIos', TenCompletionsIos: 'tenCompletionsIos'
+            }
+        },
+        {
+            file: 'Assets/_Project/Core/Leaderboards/Plugins/Android/CmposeGames.androidlib/src/main/res/values/games-ids.xml',
+            kind: 'xml',
+            keys: { games_app_id: 'androidAppId' }
+        }
+    ]
+});
+
+// Each pattern captures what comes before the value (1) and after it (2), within one line: [ \t] instead of \s
+// so a match never spans lines, and \r stays outside the value so CRLF files keep their line ends.
+const PATTERNS = {
+    cs: (key) => new RegExp(`^([ \\t]*public const string ${key} = ")[^"\\r\\n]*(";)(?=[ \\t]*\\r?$)`, 'gm'),
+    yaml: (key) => new RegExp(`^([ \\t]*${key}: )[^\\r\\n]*()`, 'gm'),
+    xml: (key) => new RegExp(`(<string name="${key}"[^>]*>)[^<]*(</string>)`, 'g')
+};
+
+function replaceOnce(text, file, kind, key, value) {
+    const re = PATTERNS[kind](key);
+    const n = (text.match(re) || []).length;
+    if (n !== 1) throw new Error(`${file}: ${key} found ${n} times`);
+    // A function replacer, so `$` sequences in the value are never interpreted
+    return text.replace(re, (_, before, after) => `${before}${value}${after}`);
+}
+
+// Writes the given id groups into the project; every target line must be there exactly once. All files are checked
+// before any is written, so a failure leaves the project as it was. Returns the groups written.
+async function writeGameIds(projectDir, ids) {
+    const written = [];
+    const updates = [];
+    for (const group of Object.keys(ID_TARGETS)) {
+        const values = ids && ids[group];
+        if (!values) continue;
+        for (const { file, kind, keys } of ID_TARGETS[group]) {
+            const abs = path.join(projectDir, file);
+            let text;
+            try {
+                text = await fs.readFile(abs, 'utf8');
+            } catch (e) {
+                throw new Error(`${file}: cannot read (${e.code || e.message})`);
+            }
+            for (const [key, field] of Object.entries(keys)) text = replaceOnce(text, file, kind, key, values[field]);
+            updates.push([abs, text]);
+        }
+        written.push(group);
+    }
+    for (const [abs, text] of updates) await fs.writeFile(abs, text);
+    return written;
+}
+
+module.exports = { ID_TARGETS, writeGameIds };

package/src/game/index.js

@@ -0,0 +1,36 @@
+'use strict';
+const { validateGame } = require('./validate');
+const { GAME_SCHEMA, gameContractFacts, gameContractVersion } = require('./contract');
+const { generateGame } = require('./generate');
+const { describeGame } = require('./describe');
+const { cloneModules } = require('./modules');
+const { applyGameIdentity } = require('./identity');
+const { writeGameIds } = require('./ids');
+const { applyGameReadme } = require('./readme');
+const { buildGameRecord, writeGameRecord } = require('./record');
+const { verifyGameProject } = require('./verifier');
+
+module.exports = {
+    validateGame,
+    generateGame,
+    describeGame,
+    GAME_SCHEMA,
+    gameContractFacts,
+    gameContractVersion,
+    cloneModules,
+    applyGameIdentity,
+    writeGameIds,
+    applyGameReadme,
+    buildGameRecord,
+    writeGameRecord,
+    verifyGameProject,
+    flags: require('./flags'),
+    guid: require('./guid'),
+    guidIntegrity: require('./guidIntegrity'),
+    unityYaml: require('./unityYaml'),
+    projectSettings: require('./projectSettings'),
+    buildScenes: require('./buildScenes'),
+    packages: require('./packages'),
+    markers: require('./markers'),
+    residue: require('./residue')
+};

package/src/game/markers.js

@@ -0,0 +1,32 @@
+const { escapeRe } = require('./unityYaml');
+
+// C# blocks a flag owns: '// cmpose:<name>' … '// /cmpose:<name>' on their own lines (any indent).
+// README blocks use ../readmeService's removeMarkedBlock instead.
+function markerRes(name) {
+    const n = escapeRe(name);
+    return {
+        open: new RegExp(`^[ \\t]*// cmpose:${n}[ \\t]*\\r?$`),
+        close: new RegExp(`^[ \\t]*// /cmpose:${n}[ \\t]*\\r?$`)
+    };
+}
+
+function removeLineMarkedBlock(text, name) {
+    const { open, close } = markerRes(name);
+    const out = [];
+    let inside = false;
+    for (const line of text.split('\n')) {
+        if (!inside && open.test(line)) { inside = true; continue; }
+        if (inside) { if (close.test(line)) inside = false; continue; }
+        if (close.test(line)) throw new Error(`cmpose:${name}: closing marker without an opening one`);
+        out.push(line);
+    }
+    if (inside) throw new Error(`cmpose:${name}: opening marker without a closing one`);
+    return out.join('\n');
+}
+
+function stripLineMarkers(text, name) {
+    const { open, close } = markerRes(name);
+    return text.split('\n').filter((line) => !open.test(line) && !close.test(line)).join('\n');
+}
+
+module.exports = { removeLineMarkedBlock, stripLineMarkers };

package/src/game/modules.js

@@ -0,0 +1,138 @@
+const path = require('path');
+const fs = require('fs-extra');
+const { cloneWithNewGuids } = require('./guid');
+const { MANIFEST } = require('./flags');
+
+// cmpose.dev/game blank modules: each one is a copy of Features/Sample with fresh guids and the Sample names
+// renamed, registered in the Game scope (one guarded installer line inside the cmpose:features markers, its using
+// line, the App asmdef reference). A copy carries the Sample's flag parts (Sample/Ads …), so the flag manifest gets
+// their twins and turning a flag off removes them from every copy. Only files are edited; Unity never runs here.
+const FEATURES = 'Assets/_Project/Features';
+const SAMPLE_DIR = `${FEATURES}/Sample`;
+const GAME_DIR = 'Assets/_Project/App/Game';
+const GAME_INSTALLER = `${GAME_DIR}/GameInstaller.cs`;
+const SAMPLE_ASSEMBLY = 'Kturker.UnityBase.Features.Sample.';
+const SAMPLE_INSTALLER_ASSEMBLY = `${SAMPLE_ASSEMBLY}Installer`;
+const SAMPLE_USING = `using ${SAMPLE_INSTALLER_ASSEMBLY};`;
+const FEATURES_START = '// cmpose:features:start';
+const FEATURES_END = '// cmpose:features:end';
+const SAMPLE_INSTALLER_LINE = 'new SampleInstaller(';
+const MODULE_NAME = /^[A-Za-z][A-Za-z0-9]*$/;
+
+const pascal = (name) => name.charAt(0).toUpperCase() + name.slice(1);
+
+// The asmdef nearest to dir, walking up to (not past) Assets
+async function owningAsmdef(projectDir, rel) {
+    for (let dir = rel; dir && dir !== '.' && dir !== 'Assets'; dir = path.posix.dirname(dir)) {
+        const abs = path.join(projectDir, dir);
+        if (!(await fs.pathExists(abs))) continue;
+        const found = (await fs.readdir(abs)).filter((n) => n.endsWith('.asmdef')).sort();
+        if (found.length) return `${dir}/${found[0]}`;
+    }
+    return null;
+}
+
+// Reads every file the wiring edits and checks its anchors before anything is written
+async function readAnchors(projectDir, fail) {
+    if (!(await fs.pathExists(path.join(projectDir, SAMPLE_DIR)))) throw fail(SAMPLE_DIR);
+    const manifestFile = path.join(projectDir, MANIFEST);
+    if (!(await fs.pathExists(manifestFile))) throw fail(MANIFEST);
+    const manifest = JSON.parse(await fs.readFile(manifestFile, 'utf8'));
+    if (!manifest || typeof manifest.flags !== 'object') throw fail(`${MANIFEST} "flags"`);
+
+    const installerFile = path.join(projectDir, GAME_INSTALLER);
+    if (!(await fs.pathExists(installerFile))) throw fail(GAME_INSTALLER);
+    const installer = await fs.readFile(installerFile, 'utf8');
+    const eol = installer.includes('\r\n') ? '\r\n' : '\n';
+    const lines = installer.split(eol);
+    const start = lines.findIndex((l) => l.trim() === FEATURES_START);
+    const end = lines.findIndex((l) => l.trim() === FEATURES_END);
+    if (start < 0 || end < start) throw fail(`${FEATURES_START} … ${FEATURES_END} in ${GAME_INSTALLER}`);
+    const sampleLine = lines.slice(start + 1, end).find((l) => l.includes(SAMPLE_INSTALLER_LINE));
+    if (!sampleLine) throw fail(`the SampleInstaller line in ${GAME_INSTALLER}`);
+    const usingAt = lines.findIndex((l) => l.trim() === SAMPLE_USING);
+    if (usingAt < 0) throw fail(`'${SAMPLE_USING}' in ${GAME_INSTALLER}`);
+
+    const asmdefRel = await owningAsmdef(projectDir, GAME_DIR);
+    if (!asmdefRel) throw fail(`the asmdef owning ${GAME_INSTALLER}`);
+    const asmdef = JSON.parse(await fs.readFile(path.join(projectDir, asmdefRel), 'utf8'));
+    const refAt = Array.isArray(asmdef.references) ? asmdef.references.indexOf(SAMPLE_INSTALLER_ASSEMBLY) : -1;
+    if (refAt < 0) throw fail(`the ${SAMPLE_INSTALLER_ASSEMBLY} reference in ${asmdefRel}`);
+
+    return {
+        manifest, manifestFile, installerFile, lines, eol, end, usingAt,
+        indent: /^\s*/.exec(sampleLine)[0], asmdefRel, asmdef, refAt
+    };
+}
+
+// Every Sample part a flag (other than sample itself) removes gets the copy's twin
+function addFlagTwins(manifest, names) {
+    for (const [flagName, flag] of Object.entries(manifest.flags)) {
+        if (flagName === 'sample' || !flag || typeof flag !== 'object') continue;
+        for (const name of names) {
+            const p = pascal(name);
+            if (Array.isArray(flag.paths)) {
+                const twins = flag.paths.filter((x) => x.startsWith(`${SAMPLE_DIR}/`))
+                    .map((x) => `${FEATURES}/${p}/${x.slice(SAMPLE_DIR.length + 1)}`);
+                flag.paths.push(...twins.filter((t) => !flag.paths.includes(t)));
+            }
+            if (Array.isArray(flag.asmdefs)) {
+                const twins = flag.asmdefs.filter((x) => x.startsWith(SAMPLE_ASSEMBLY))
+                    .map((x) => `Kturker.UnityBase.Features.${p}.${x.slice(SAMPLE_ASSEMBLY.length)}`);
+                flag.asmdefs.push(...twins.filter((t) => !flag.asmdefs.includes(t)));
+            }
+        }
+    }
+}
+
+async function cloneModules(projectDir, features, { seed }) {
+    const names = [...features];
+    if (!names.length) return [];
+    for (const name of names) {
+        if (typeof name !== 'string' || !MODULE_NAME.test(name)) throw new Error(`module ${name}: not a valid module name`);
+        if (pascal(name) === 'Sample') throw new Error(`module ${name}: clashes with the template's Sample`);
+        if (await fs.pathExists(path.join(projectDir, FEATURES, pascal(name)))) {
+            throw new Error(`module ${name}: ${FEATURES}/${pascal(name)} already exists`);
+        }
+    }
+    let anchors;
+    try {
+        anchors = await readAnchors(projectDir, (what) => new Error(`module ${names[0]}: ${what} not found in the template`));
+    } catch (error) {
+        if (error instanceof SyntaxError) throw new Error(`module ${names[0]}: ${error.message}`);
+        throw error;
+    }
+
+    const created = [];
+    for (const name of names) {
+        const p = pascal(name);
+        // Localization keys ('sample.x') are renamed only where they are keys: string literals and JSON keys
+        // ("sample.x") and the prefabs' 'key: sample.x'; a C# member named sample ('sample.Clicked') stays.
+        // The literal "sample" is the save slot (SavedCompletionCounter's SaveSchema): each copy gets its own
+        await cloneWithNewGuids(path.join(projectDir, SAMPLE_DIR), path.join(projectDir, FEATURES, p), {
+            seed: `${seed}:${name}`,
+            rename: [{ from: 'Sample', to: p }, { from: 'sample.json', to: `${name}.json` },
+                { from: '"sample.', to: `"${name}.` }, { from: 'key: sample.', to: `key: ${name}.` },
+                { from: '"sample"', to: `"${name}"` }]
+        });
+        created.push(`${FEATURES}/${p}`);
+    }
+
+    const { manifest, manifestFile, lines, eol, end, usingAt, indent, asmdef, refAt } = anchors;
+    addFlagTwins(manifest, names);
+    await fs.writeFile(manifestFile, `${JSON.stringify(manifest, null, 2)}\n`);
+
+    // Installer lines go before the end marker (in order), using lines right after the Sample one
+    const installs = names.map((n) => `${indent}if (registerViews) new ${pascal(n)}Installer(registerViews).Install(builder);`);
+    const usings = names.map((n) => `using Kturker.UnityBase.Features.${pascal(n)}.Installer;`);
+    const next = [...lines];
+    next.splice(end, 0, ...installs);
+    next.splice(usingAt + 1, 0, ...usings);
+    await fs.writeFile(anchors.installerFile, next.join(eol));
+
+    asmdef.references.splice(refAt + 1, 0, ...names.map((n) => `Kturker.UnityBase.Features.${pascal(n)}.Installer`));
+    await fs.writeFile(path.join(projectDir, anchors.asmdefRel), `${JSON.stringify(asmdef, null, 4)}\n`);
+    return created;
+}
+
+module.exports = { cloneModules };

package/src/game/packages.js

@@ -0,0 +1,31 @@
+const path = require('path');
+const fs = require('fs-extra');
+
+// A scope covers a package when it equals the package name or is a dotted prefix of it (UPM's rule)
+function scopeInUse(scope, names) {
+    return names.some((n) => n === scope || n.startsWith(`${scope}.`));
+}
+
+function removePackages(manifest, ids) {
+    const out = JSON.parse(JSON.stringify(manifest));
+    const drop = new Set(ids);
+    out.dependencies = Object.fromEntries(Object.entries(out.dependencies || {}).filter(([name]) => !drop.has(name)));
+    if (Array.isArray(out.scopedRegistries)) {
+        const names = Object.keys(out.dependencies);
+        out.scopedRegistries = out.scopedRegistries
+            .map((r) => ({ ...r, scopes: (r.scopes || []).filter((s) => scopeInUse(s, names)) }))
+            .filter((r) => r.scopes.length > 0);
+        if (out.scopedRegistries.length === 0) delete out.scopedRegistries;
+    }
+    return out;
+}
+
+// Unity rebuilds packages-lock.json on the next open; a stale lock would pin removed packages
+async function removePackagesInProject(projectPath, ids) {
+    const manifestPath = path.join(projectPath, 'Packages', 'manifest.json');
+    const manifest = JSON.parse(await fs.readFile(manifestPath, 'utf8'));
+    await fs.writeFile(manifestPath, `${JSON.stringify(removePackages(manifest, ids), null, 2)}\n`);
+    await fs.remove(path.join(projectPath, 'Packages', 'packages-lock.json'));
+}
+
+module.exports = { removePackages, removePackagesInProject };

package/src/game/projectSettings.js

@@ -0,0 +1,53 @@
+const {
+    UnityYamlError, setScalar, setMapEntry, getMapEntry, removeMapEntry, setList
+} = require('./unityYaml');
+
+// PlayerSettings is document '--- !u!129 &1' of ProjectSettings/ProjectSettings.asset
+const PLAYER = { classId: 129, fileId: 1 };
+
+// Plain YAML scalars only: no line breaks, no leading indicator or space, no ': ' or ' #', no trailing space.
+// Whether a value is a valid name or ID is the validator's job, not this file's.
+function plain(name, value) {
+    const s = String(value === undefined || value === null ? '' : value);
+    if (s.length === 0 || /[\r\n]/.test(s) || /^[\s\-?:,[\]{}#&*!|>'"%@`]/.test(s) || /: /.test(s) || / #/.test(s) || /\s$/.test(s)) {
+        throw new UnityYamlError(`${name}: '${s}' cannot be written as a plain YAML value`, { key: name });
+    }
+    return s;
+}
+
+function applyIdentity(text, { companyName, productName, bundleId, version, androidMinSdk, iosTarget, urlScheme }) {
+    if (!Number.isInteger(androidMinSdk)) {
+        throw new UnityYamlError('androidMinSdk must be an integer', { key: 'androidMinSdk' });
+    }
+    const doc = PLAYER;
+    let out = text;
+    out = setScalar(out, 'companyName', plain('companyName', companyName), { doc });
+    out = setScalar(out, 'productName', plain('productName', productName), { doc });
+    out = setScalar(out, 'bundleVersion', plain('version', version), { doc });
+    out = setScalar(out, 'overrideDefaultApplicationIdentifier', '1', { doc });
+    out = setMapEntry(out, 'applicationIdentifier', 'Android', plain('bundleId', bundleId), { doc });
+    out = setMapEntry(out, 'applicationIdentifier', 'iPhone', plain('bundleId', bundleId), { doc });
+    out = setScalar(out, 'AndroidMinSdkVersion', String(androidMinSdk), { doc });
+    out = setScalar(out, 'iOSTargetOSVersionString', plain('iosTarget', iosTarget), { doc });
+    out = setList(out, 'iOSURLSchemes', urlScheme ? [plain('urlScheme', urlScheme)] : [], { doc });
+    return out;
+}
+
+const SYMBOL = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+// Unity 6 keeps scripting defines per build target, ';'-separated; an empty target has no entry
+function setDefines(text, target, symbols) {
+    for (const s of symbols) {
+        if (!SYMBOL.test(s)) throw new UnityYamlError(`scripting define '${s}' is not a valid symbol`, { key: target });
+    }
+    return symbols.length
+        ? setMapEntry(text, 'scriptingDefineSymbols', target, symbols.join(';'), { doc: PLAYER })
+        : removeMapEntry(text, 'scriptingDefineSymbols', target, { doc: PLAYER });
+}
+
+function getDefines(text, target) {
+    const value = getMapEntry(text, 'scriptingDefineSymbols', target, { doc: PLAYER });
+    return value ? value.split(';').filter(Boolean) : [];
+}
+
+module.exports = { PLAYER, applyIdentity, setDefines, getDefines };

package/src/game/readme.js

@@ -0,0 +1,20 @@
+'use strict';
+const path = require('path');
+const fs = require('fs-extra');
+const { removeMarkedBlock } = require('../readmeService');
+const { GAME_SCHEMA } = require('./contract');
+
+// The generated README keeps the <!-- cmpose:<flag> --> sections of the flags that are on; other marked
+// sections (cmpose:ci) are not flags and stay. Returns false when the project has no README.
+async function applyGameReadme(projectDir, { flags }) {
+    const file = path.join(projectDir, 'README.md');
+    if (!(await fs.pathExists(file))) return false;
+    const on = new Set(flags);
+    const before = await fs.readFile(file, 'utf8');
+    let text = before;
+    for (const flag of GAME_SCHEMA.flags) if (!on.has(flag)) text = removeMarkedBlock(text, `cmpose:${flag}`);
+    if (text !== before) await fs.writeFile(file, text);
+    return true;
+}
+
+module.exports = { applyGameReadme };

package/src/game/record.js

@@ -0,0 +1,47 @@
+'use strict';
+const path = require('path');
+const fs = require('fs-extra');
+const { GAME_SCHEMA } = require('./contract');
+
+const RECORD_PATH = path.join('.cmpose', 'generation.json');
+
+// Whether each ID group's real values were written ('custom'), the template's test IDs stay ('test') or its
+// flag is off ('off'). The values themselves are never recorded.
+function idStatuses(flags, ids) {
+    const out = {};
+    for (const [group, { flag }] of Object.entries(GAME_SCHEMA.idGroups)) {
+        if (!flags.includes(flag)) out[group] = 'off';
+        else out[group] = ids && ids[group] ? 'custom' : 'test';
+    }
+    return out;
+}
+
+/** The .cmpose/generation.json content of a generated Unity game (no personal data, no ID values);
+ * generatorVersion names the caller (e.g. mcp@0.2.0), null when not given */
+function buildGameRecord({ template, coreVersion, generatorVersion = null, value, now = new Date() }) {
+    return {
+        generator: '@cmpose/core',
+        coreVersion,
+        generatorVersion: generatorVersion || null,
+        engine: 'unity',
+        unityVersion: GAME_SCHEMA.unityVersion,
+        templateType: value.templateType,
+        render: value.render,
+        flags: value.flags.slice(),
+        features: value.features.slice(),
+        ci: value.ci === true,
+        minSdk: value.minSdk,
+        iosVersion: value.iosVersion,
+        ids: idStatuses(value.flags, value.ids),
+        template: { repo: template.repo, ref: template.ref, commit: template.commit },
+        generatedAt: now.toISOString()
+    };
+}
+
+async function writeGameRecord(projectDir, record) {
+    const file = path.join(projectDir, RECORD_PATH);
+    await fs.outputFile(file, `${JSON.stringify(record, null, 2)}\n`);
+    return file;
+}
+
+module.exports = { RECORD_PATH, buildGameRecord, writeGameRecord };

package/src/game/residue.js

@@ -0,0 +1,40 @@
+const path = require('path');
+const fs = require('fs-extra');
+
+// Unity caches and local state never ship and are never scanned
+const ALWAYS_SKIPPED = new Set(['Library', 'Temp', 'Logs', 'UserSettings', 'obj', '.git']);
+const TEXT_EXTENSIONS = new Set(['.cs', '.asmdef', '.asmref', '.json', '.asset', '.unity', '.prefab', '.mat', '.xml',
+    '.plist', '.xcprivacy', '.md', '.txt', '.gradle', '.properties', '.mm', '.m', '.h', '.swift', '.meta', '.yml', '.yaml']);
+
+async function walk(abs, rel, out) {
+    for (const entry of await fs.readdir(abs, { withFileTypes: true })) {
+        const r = rel ? `${rel}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) {
+            if (!rel && ALWAYS_SKIPPED.has(entry.name)) continue;
+            if (entry.name === '.git') continue;
+            await walk(path.join(abs, entry.name), r, out);
+        } else if (TEXT_EXTENSIONS.has(path.extname(entry.name))) {
+            out.push(r);
+        }
+    }
+}
+
+const ignoredBy = (prefixes, rel) => prefixes.some((p) => rel === p || rel.startsWith(p));
+
+async function findResidue(dir, rules, { ignore = [] } = {}) {
+    const files = [];
+    await walk(dir, '', files);
+    const problems = new Set();
+    for (const rel of files.sort()) {
+        if (ignoredBy(ignore, rel)) continue;
+        const text = await fs.readFile(path.join(dir, rel), 'utf8');
+        for (const rule of rules) {
+            if (rule.extensions && !rule.extensions.includes(path.extname(rel))) continue;
+            if (ignoredBy(rule.ignore || [], rel)) continue;
+            for (const token of rule.tokens) if (text.includes(token)) problems.add(`${rule.name} ${token} in ${rel}`);
+        }
+    }
+    return [...problems].sort();
+}
+
+module.exports = { findResidue };