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.

15.7 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
//
// AndroidManifest.xml, compiled — the format aapt2 produces and the platform
// parses (binary XML: a string pool, a resource map, and one chunk per node).
//
// Written rather than shelled out to, because `aapt2` is the reason packaging an
// APK used to need the whole Android SDK. Everything else the assembler does is a
// zip and a signature; this was the last external tool in the path between an
// editor export and an installable app.
//
// The scope is deliberately OUR manifest: elements, attributes, and the four value
// kinds it uses. Nothing here compiles resources — an APK with no resources of its
// own is what the native host ships, and the one reference it makes
// (@android:style/Theme.NoTitleBar.Fullscreen) is a FRAMEWORK id, resolved by the
// platform rather than by a table we would have to emit.
//
// The platform resolves a framework attribute BY ITS RESOURCE ID, not by the name
// string — a wrong id is silently ignored rather than rejected — so the ids below
// are pinned against AOSP's public.xml by `desktop/tests/android-manifest.test.ts`.

/** The namespace every framework attribute lives in. */
export const ANDROID_NS = 'http://schemas.android.com/apk/res/android';

/** AOSP public attribute ids, for the attributes our manifest uses. */
export const ANDROID_ATTR_IDS = {
    theme: 0x01010000,
    label: 0x01010001,
    icon: 0x01010002,
    name: 0x01010003,
    hasCode: 0x0101000c,
    exported: 0x01010010,
    screenOrientation: 0x0101001e,
    configChanges: 0x0101001f,
    value: 0x01010024,
    minSdkVersion: 0x0101020c,
    versionCode: 0x0101021b,
    versionName: 0x0101021c,
    targetSdkVersion: 0x01010270,
    required: 0x0101028e,
    extractNativeLibs: 0x010104ea,
    usesCleartextTraffic: 0x010104ec,
    version: 0x01010519,
};

/** AOSP public style ids, for the `@android:style/...` a manifest may name. */
export const ANDROID_STYLE_IDS = {
    'Theme.NoTitleBar': 0x01030006,
    'Theme.NoTitleBar.Fullscreen': 0x01030007,
};

// Res_value data types.
const TYPE_REFERENCE = 0x01;
const TYPE_STRING = 0x03;
import { symbolicAttrValue } from './androidAttrValues.js';

const TYPE_INT_DEC = 0x10;
const TYPE_INT_HEX = 0x11;
const TYPE_INT_BOOLEAN = 0x12;

const NO_ENTRY = 0xffffffff;

// =============================================================================
// A very small XML reader
// =============================================================================

const ENTITIES = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'" };

function unescape(text) {
    return text.replace(/&(#x?[0-9a-fA-F]+|[a-z]+);/g, (m, ref) => {
        if (ref[0] === '#') return String.fromCodePoint(parseInt(ref[1] === 'x' ? ref.slice(2) : ref.slice(1), ref[1] === 'x' ? 16 : 10));
        return ref in ENTITIES ? ENTITIES[ref] : m;
    });
}

/**
 * Parse the XML subset a manifest is written in: elements, attributes, comments
 * and the declaration. Text nodes are ignored — a manifest has none that matter,
 * and accepting them silently would hide a typo.
 *
 * @returns {{name: string, attrs: Array<{prefix: string|null, name: string, value: string}>,
 *            children: Array<object>, line: number}} the root element
 */
export function parseXml(text) {
    let i = 0;
    let line = 1;
    const advance = (to) => {
        for (let k = i; k < to; k++) if (text[k] === '\n') line++;
        i = to;
    };
    const skipSpace = () => { while (i < text.length && /\s/.test(text[i])) { if (text[i] === '\n') line++; i++; } };

    let root = null;
    const stack = [];
    const attach = (node) => {
        if (stack.length > 0) stack[stack.length - 1].children.push(node);
        else if (!root) root = node;
        else throw new Error(`XML: a second root element <${node.name}> (line ${node.line})`);
    };

    while (i < text.length) {
        const lt = text.indexOf('<', i);
        if (lt < 0) break;
        advance(lt);
        if (text.startsWith('<?', i)) { advance(text.indexOf('?>', i) + 2); continue; }
        if (text.startsWith('<!--', i)) { advance(text.indexOf('-->', i) + 3); continue; }
        if (text.startsWith('</', i)) {
            const end = text.indexOf('>', i);
            const name = text.slice(i + 2, end).trim();
            const open = stack.pop();
            if (!open || open.name !== name) throw new Error(`XML: </${name}> does not close <${open?.name}> (line ${line})`);
            advance(end + 1);
            continue;
        }

        // <name attr="value" ... > or <name ... />
        advance(i + 1);
        const nameStart = i;
        while (i < text.length && !/[\s/>]/.test(text[i])) i++;
        const node = { name: text.slice(nameStart, i), attrs: [], children: [], line };
        for (;;) {
            skipSpace();
            if (text.startsWith('/>', i)) { advance(i + 2); attach(node); break; }
            if (text[i] === '>') { advance(i + 1); attach(node); stack.push(node); break; }
            const attrStart = i;
            while (i < text.length && !/[\s=]/.test(text[i])) i++;
            const qualified = text.slice(attrStart, i);
            skipSpace();
            if (text[i] !== '=') throw new Error(`XML: attribute ${qualified} has no value (line ${line})`);
            advance(i + 1);
            skipSpace();
            const quote = text[i];
            if (quote !== '"' && quote !== "'") throw new Error(`XML: unquoted value for ${qualified} (line ${line})`);
            const valueEnd = text.indexOf(quote, i + 1);
            const value = unescape(text.slice(i + 1, valueEnd));
            advance(valueEnd + 1);
            const colon = qualified.indexOf(':');
            node.attrs.push(colon < 0
                ? { prefix: null, name: qualified, value }
                : { prefix: qualified.slice(0, colon), name: qualified.slice(colon + 1), value });
        }
    }
    if (stack.length > 0) throw new Error(`XML: <${stack[stack.length - 1].name}> is never closed`);
    if (!root) throw new Error('XML: no root element');
    return root;
}

// =============================================================================
// The string pool
// =============================================================================

class StringPool {
    constructor() {
        this.strings = [];
        this.index = new Map();
    }

    /** @returns the pool index, adding the string if it is new. */
    add(s) {
        const known = this.index.get(s);
        if (known !== undefined) return known;
        const at = this.strings.length;
        this.strings.push(s);
        this.index.set(s, at);
        return at;
    }

    /**
     * UTF-16 rather than UTF-8: every parser accepts it, and its length rules have
     * no surrogate-vs-code-unit subtlety to get wrong. A manifest is a few hundred
     * bytes either way.
     */
    encode() {
        const bodies = this.strings.map((s) => {
            const chars = Buffer.from(s, 'utf16le');
            const units = chars.length / 2;
            if (units > 0x7fff) throw new Error('string pool entry too long');
            const out = Buffer.alloc(2 + chars.length + 2);
            out.writeUInt16LE(units, 0);
            chars.copy(out, 2);
            return out;   // trailing UTF-16 NUL is the zero-filled tail
        });
        const offsets = Buffer.alloc(this.strings.length * 4);
        let at = 0;
        bodies.forEach((b, n) => { offsets.writeUInt32LE(at, n * 4); at += b.length; });
        const data = Buffer.concat(bodies);
        const padding = (4 - (data.length % 4)) % 4;
        const headerSize = 28;
        const stringsStart = headerSize + offsets.length;
        const size = stringsStart + data.length + padding;

        const header = Buffer.alloc(headerSize);
        header.writeUInt16LE(0x0001, 0);          // RES_STRING_POOL_TYPE
        header.writeUInt16LE(headerSize, 2);
        header.writeUInt32LE(size, 4);
        header.writeUInt32LE(this.strings.length, 8);
        header.writeUInt32LE(0, 12);              // no styles
        header.writeUInt32LE(0, 16);              // flags: UTF-16, unsorted
        header.writeUInt32LE(stringsStart, 20);
        header.writeUInt32LE(0, 24);              // stylesStart
        return Buffer.concat([header, offsets, data, Buffer.alloc(padding)]);
    }
}

// =============================================================================
// Values
// =============================================================================

/**
 * How a manifest attribute's text is typed. Order matters: references before
 * anything, then the two integer spellings, then booleans, then string.
 *
 * `@android:style/...` is a framework id, known here. `@mipmap/...` and friends
 * are the APP's own resources, whose ids belong to whoever built the resource
 * table — so they are passed in rather than guessed.
 */
function typedValue(value, pool, references, name) {
    // Attributes whose words ARE numbers (configChanges, screenOrientation) resolve
    // first: their text looks like a plain string, and shipping it as one is an APK
    // the platform refuses to install.
    const symbolic = name === undefined ? null : symbolicAttrValue(name, value);
    if (symbolic !== null) {
        return { type: TYPE_INT_DEC, data: symbolic >>> 0, raw: NO_ENTRY };
    }
    const style = /^@android:style\/(.+)$/.exec(value);
    if (style) {
        const id = ANDROID_STYLE_IDS[style[1]];
        if (id === undefined) throw new Error(`Unknown framework style @android:style/${style[1]}`);
        return { type: TYPE_REFERENCE, data: id, raw: NO_ENTRY };
    }
    if (value.startsWith('@')) {
        const id = references[value];
        if (id === undefined) throw new Error(`No resource id for ${value} — the assembler declares what it packages.`);
        return { type: TYPE_REFERENCE, data: id >>> 0, raw: NO_ENTRY };
    }
    if (value === 'true' || value === 'false') {
        return { type: TYPE_INT_BOOLEAN, data: value === 'true' ? 0xffffffff : 0, raw: NO_ENTRY };
    }
    if (/^0x[0-9a-fA-F]+$/.test(value)) {
        return { type: TYPE_INT_HEX, data: Number.parseInt(value, 16) >>> 0, raw: NO_ENTRY };
    }
    if (/^-?\d+$/.test(value)) {
        return { type: TYPE_INT_DEC, data: Number.parseInt(value, 10) >>> 0, raw: NO_ENTRY };
    }
    const at = pool.add(value);
    return { type: TYPE_STRING, data: at, raw: at };
}

// =============================================================================
// The encoder
// =============================================================================

function chunk(type, headerExtra, body) {
    const headerSize = 8 + headerExtra.length;
    const header = Buffer.alloc(8);
    header.writeUInt16LE(type, 0);
    header.writeUInt16LE(headerSize, 2);
    header.writeUInt32LE(headerSize + body.length, 4);
    return Buffer.concat([header, headerExtra, body]);
}

/** The 8 bytes every XML node chunk carries after its header: line + comment. */
function nodeHeaderExtra(line) {
    const extra = Buffer.alloc(8);
    extra.writeUInt32LE(line, 0);
    extra.writeUInt32LE(NO_ENTRY, 4);
    return extra;
}

/**
 * Compile a parsed manifest to binary XML.
 *
 * Attribute-name strings are pooled FIRST, in the order the resource map lists
 * their ids: the platform reads an attribute's id by its position in that map, so
 * the two are one structure written as two.
 *
 * @param {object} root The element from {@link parseXml}.
 * @param {Record<string, number>} [references] The app's own resource ids, by
 *        `@type/name` — what an `android:icon` resolves through.
 * @returns {Buffer}
 */
export function encodeBinaryXml(root, references = {}) {
    const pool = new StringPool();

    // Pass 1: every framework attribute name, in first-use order.
    const attrIds = [];
    const walkNames = (node) => {
        for (const attr of node.attrs) {
            if (attr.prefix !== 'android') continue;
            const id = ANDROID_ATTR_IDS[attr.name];
            if (id === undefined) {
                throw new Error(`No public resource id known for android:${attr.name} — add it to `
                    + 'ANDROID_ATTR_IDS (the platform resolves attributes by id, so guessing is not an option).');
            }
            if (pool.index.has(attr.name)) continue;
            pool.add(attr.name);
            attrIds.push(id);
        }
        node.children.forEach(walkNames);
    };
    walkNames(root);
    // Nothing else may take a slot the resource map covers.
    const mapSize = pool.strings.length;

    const nsPrefix = pool.add('android');
    const nsUri = pool.add(ANDROID_NS);

    // Pass 2: the node chunks. Values and element names join the pool as they are
    // reached, which is why the map's slots had to be claimed first.
    const nodes = [];
    const emit = (node) => {
        // Sorted by resource id, which is not a style: the platform reads an
        // element's attributes with a BINARY SEARCH over this array, so an
        // out-of-order attribute is one the platform cannot find. An
        // android:exported it fails to find reads as absent — and an activity with
        // an intent filter and no explicit `exported` is refused outright on
        // Android 12+. Attributes with no resource id sort last; the manifest has
        // none today, and a custom namespace is not looked up by id anyway.
        const attrs = node.attrs
            .filter((a) => a.name !== 'xmlns' && a.prefix !== 'xmlns')
            .map((a) => ({
                id: a.prefix === 'android' ? ANDROID_ATTR_IDS[a.name] : Number.MAX_SAFE_INTEGER,
                ns: a.prefix === 'android' ? nsUri : NO_ENTRY,
                name: pool.add(a.name),
                value: typedValue(a.value, pool, references, a.name),
            }))
            .sort((x, y) => x.id - y.id);
        const name = pool.add(node.name);

        const ext = Buffer.alloc(20 + attrs.length * 20);
        ext.writeUInt32LE(NO_ENTRY, 0);           // element namespace
        ext.writeUInt32LE(name, 4);
        ext.writeUInt16LE(20, 8);                 // attributeStart
        ext.writeUInt16LE(20, 10);                // attributeSize
        ext.writeUInt16LE(attrs.length, 12);
        ext.writeUInt16LE(0, 14);                 // idIndex — no android:id in a manifest
        ext.writeUInt16LE(0, 16);                 // classIndex
        ext.writeUInt16LE(0, 18);                 // styleIndex
        attrs.forEach((a, n) => {
            const at = 20 + n * 20;
            ext.writeUInt32LE(a.ns, at);
            ext.writeUInt32LE(a.name, at + 4);
            ext.writeUInt32LE(a.value.raw, at + 8);
            ext.writeUInt16LE(8, at + 12);        // Res_value size
            ext.writeUInt8(0, at + 14);           // res0
            ext.writeUInt8(a.value.type, at + 15);
            ext.writeUInt32LE(a.value.data, at + 16);
        });
        nodes.push(chunk(0x0102, nodeHeaderExtra(node.line), ext));

        node.children.forEach(emit);

        const end = Buffer.alloc(8);
        end.writeUInt32LE(NO_ENTRY, 0);
        end.writeUInt32LE(name, 4);
        nodes.push(chunk(0x0103, nodeHeaderExtra(node.line), end));
    };

    const namespace = (type) => {
        const body = Buffer.alloc(8);
        body.writeUInt32LE(nsPrefix, 0);
        body.writeUInt32LE(nsUri, 4);
        return chunk(type, nodeHeaderExtra(root.line), body);
    };

    const startNs = namespace(0x0100);
    emit(root);
    const endNs = namespace(0x0101);

    const map = Buffer.alloc(mapSize * 4);
    attrIds.forEach((id, n) => map.writeUInt32LE(id, n * 4));

    const body = Buffer.concat([pool.encode(), chunk(0x0180, Buffer.alloc(0), map), startNs, ...nodes, endNs]);
    return chunk(0x0003, Buffer.alloc(0), body);   // RES_XML_TYPE
}

/** Compile manifest SOURCE (the filled template) to the bytes an APK carries. */
export function compileManifest(xml, references = {}) {
    return encodeBinaryXml(parseXml(xml), references);
}