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.

13.2 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
//
// The Android Studio project an Android export ships, written directly — the
// Android side of iosProject.js, and the same bargain: the runtime template
// carries the engine's compiled half, the export carries the game, and what the
// user opens is an ordinary project of their platform's own kind.
//
// It exists because an APK is a dead end for anyone who needs to add an SDK, a
// permission, a service or their own Activity. The one-click package stays for
// everyone who does not.

import { cp, mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
import { existsSync } from 'node:fs';
import path from 'node:path';
import { fillTemplate, androidManifestValues } from './nativeApp.js';

/** Android Gradle Plugin the emitted project asks for. */
const AGP_VERSION = '8.7.3';
/** compileSdk. min/target come from the manifest template, which owns them. */
const COMPILE_SDK = 34;

/** The Gradle project's own files, which are never mistaken for game content. */
const PROJECT_ENTRIES = [
    'app', 'settings.gradle.kts', 'build.gradle.kts', 'gradle.properties',
    'gradle', 'gradlew', 'gradlew.bat', 'README.md', '.gitignore',
];

/** A Gradle project name (and Android Studio window title) that needs no quoting. */
function projectName(appName) {
    return appName.replace(/[^A-Za-z0-9]+/g, '') || 'EstellaGame';
}

/**
 * Turn the packaging manifest template into the one a Gradle build wants.
 *
 * Same file, same substitutions, so the manifest an APK carries and the manifest
 * a project builds are the same document. What differs is where identity lives:
 * AGP 8 rejects `package` and the version attributes in a manifest and reads them
 * from the build script, and it ignores `<uses-sdk>` in favour of the same. So
 * those move out — and their values move INTO the build script rather than being
 * restated, which is why they are returned here.
 *
 * @returns {{xml: string, minSdk: number, targetSdk: number}}
 */
export function gradleManifest(templateXml, app) {
    // A project compiles the Java shim from source, so there is always code.
    const filled = fillTemplate(templateXml, androidManifestValues(app, { hasCode: true }));

    const minSdk = Number(/android:minSdkVersion="(\d+)"/.exec(filled)?.[1] ?? 29);
    const targetSdk = Number(/android:targetSdkVersion="(\d+)"/.exec(filled)?.[1] ?? 33);

    const xml = filled
        // Horizontal whitespace only: `\s*` also eats the next line's indent, which
        // pulls the element after it onto the manifest tag's own line.
        .replace(/^[^\S\n]*<uses-sdk[^>]*\/>[^\S\n]*\r?\n/m, '')
        // The line ending goes with the line: a template with CRLF would otherwise
        // leave its `\r` behind on the tag these were removed from.
        .replace(/\r?\n[^\S\n]*package="[^"]*"/, '')
        .replace(/\r?\n[^\S\n]*android:versionCode="[^"]*"/, '')
        .replace(/\r?\n[^\S\n]*android:versionName="[^"]*"/, '');

    return { xml, minSdk, targetSdk };
}

/** `settings.gradle.kts` — where the plugin and its dependencies come from. */
export function renderSettingsGradle(name) {
    return `pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}

rootProject.name = "${name}"
include(":app")
`;
}

/** The root build script: declares the plugin, applies it in :app. */
export function renderRootGradle() {
    return `plugins {
    id("com.android.application") version "${AGP_VERSION}" apply false
}
`;
}

/**
 * `app/build.gradle.kts` — the file a game edits.
 *
 * Identity, SDK levels and the ABI filter live here because AGP owns them; the
 * engine's prebuilt libraries are picked up from jniLibs by convention, so
 * nothing here has to name them.
 */
export function renderAppGradle(o) {
    const abis = o.abis.map((abi) => `"${abi}"`).join(', ');
    return `plugins {
    id("com.android.application")
}

android {
    namespace = "${o.appId}"
    compileSdk = ${COMPILE_SDK}

    defaultConfig {
        applicationId = "${o.appId}"
        minSdk = ${o.minSdk}
        targetSdk = ${o.targetSdk}
        versionCode = ${o.versionCode}
        versionName = "${o.version}"

        // The engine ships as prebuilt libraries under src/main/jniLibs; this is
        // the set of architectures they were built for.
        ndk {
            abiFilters += listOf(${abis})
        }
    }

    // The host maps its libraries out of the installed package, which is also what
    // lets an App Bundle split them per device.
    packaging {
        jniLibs {
            useLegacyPackaging = false
        }
    }

    // Your own Java or Kotlin, and its resources, live under src/game. Exporting
    // again rewrites src/main (the host's own classes among it) and never this.
    sourceSets {
        getByName("main") {
            java.srcDir("src/game/java")
            resources.srcDir("src/game/resources")
        }
    }

    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }

    buildTypes {
        release {
            isMinifyEnabled = false
            // Add a signingConfig here to build an upload-ready release. Until then
            // \`assembleRelease\` produces an unsigned APK and \`assembleDebug\` a
            // debug-signed one that installs on a device.
        }
    }
}

dependencies {
    // Your SDKs go here — this project is an ordinary Android application.
}
`;
}

export function renderGradleProperties() {
    return `org.gradle.jvmargs=-Xmx2048m
android.useAndroidX=true
android.nonTransitiveRClass=true
`;
}

export function renderProjectReadme(o) {
    return `# ${o.name}

An Android Studio project exported from Estella. Open this folder in Android
Studio (or run \`gradle :app:assembleDebug\`) — no Android SDK setup beyond the
one Studio installs, and no Estella toolchain.

## What is here

    app/src/main/assets/      the exported game: cooked content + its configs
    app/src/main/jniLibs/     the engine, prebuilt for ${o.abis.join(' and ')}
    app/src/main/java/        the host's Java shim (the IME side of a text field)
    app/src/main/res/         the launcher icon
    app/src/main/AndroidManifest.xml
    app/build.gradle.kts      identity, SDK levels, and where your SDKs go

## Adding an SDK

Add the dependency in \`app/build.gradle.kts\` and whatever the SDK asks of the
manifest. The game itself is native and starts from \`NativeActivity\`; a Java SDK
that needs an entry point can subclass it and name the subclass in the manifest.

## Calling your Java from the game

The game reaches your code by name through \`com.estella.host.NativeChannel\`.
Put your classes under \`app/src/game/java\` (a re-export leaves that folder
alone) and register what they answer from a plugin:

    package com.example.game;

    public final class GamePlugin implements com.estella.host.NativeChannel.Plugin {
        @Override public void register(android.app.Activity activity) {
            com.estella.host.NativeChannel.register("ads.show", (args, reply) -> {
                // show the ad with your SDK, then, when it has closed:
                reply.resolve("{\\"completed\\":true}");
            });
        }
    }

Name the plugin in \`app/src/game/resources/META-INF/services/com.estella.host.NativeChannel$Plugin\`
(one class name per line), which is how it is found before the first frame:

    com.example.game.GamePlugin

In the game, \`await NativeChannel.call('ads.show', { kind: 'rewarded', unitId })\`
runs the handler on the UI thread and resolves with what it answered. Answering
\`ads.show\` is also what makes the engine's own \`Ads\` service work on a device.
\`NativeChannel.emit(event, json)\` tells the game something it did not ask for.

## Re-exporting

Exporting again from Estella rewrites \`app/src/main/assets\`, the manifest, the
libraries and the icon — the content, in other words. \`app/build.gradle.kts\` and
anything else you edit is left alone.
`;
}

export function renderGitignore() {
    return `.gradle/
build/
local.properties
.idea/
*.iml
`;
}

/**
 * Write the Android Studio project into an export, in place: the export directory
 * BECOMES the project. The cooked content moves once, into the module's assets —
 * where Gradle expects it and where the host reads it from the installed package,
 * so the layout inside an APK is byte-for-byte what the one-click path produces.
 *
 * Re-exporting overwrites what the export owns and leaves the build scripts alone,
 * so a project that has grown an SDK survives its game being rebuilt.
 *
 * @param {string} contentDir  The export (cooked content + the two configs).
 * @param {{id: string, name: string, version: string, versionCode: number,
 *          orientation: 'landscape'|'portrait'}} app  From `app.config.json`.
 * @param {{libs: string, java: string, manifestIn: string, icon: string,
 *          bytecode?: string}} sources  Out of the installed runtime template.
 * @param {Buffer} [icon] The launcher icon; the template's default when absent.
 * @returns {Promise<string>} The project directory, to reveal or open.
 */
export async function emitAndroidGradleProject(contentDir, app, sources, icon) {
    const name = projectName(app.name);
    const appDir = path.join(contentDir, 'app');
    const mainDir = path.join(appDir, 'src', 'main');
    const assetsDir = path.join(mainDir, 'assets');

    const abis = (await readdir(sources.libs, { withFileTypes: true }))
        .filter((e) => e.isDirectory())
        .map((e) => e.name)
        .sort();
    if (abis.length === 0) {
        throw new Error(`The runtime template at ${sources.libs} carries no native libraries.`);
    }

    // Everything the export wrote, before this function adds anything that could be
    // mistaken for it.
    const exported = (await readdir(contentDir, { withFileTypes: true }))
        .filter((e) => !PROJECT_ENTRIES.includes(e.name))
        .map((e) => e.name);

    // The generated half is rewritten wholesale so a re-export cannot inherit the
    // last one's assets, libraries or manifest. The build scripts are not in here:
    // they are the half the user owns.
    await rm(path.join(mainDir, 'assets'), { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
    await rm(path.join(mainDir, 'jniLibs'), { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
    await rm(path.join(mainDir, 'java'), { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
    await rm(path.join(mainDir, 'res'), { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });

    await mkdir(assetsDir, { recursive: true });
    for (const entry of exported) {
        await rename(path.join(contentDir, entry), path.join(assetsDir, entry));
    }

    // The SDK bytecode rides along as an asset, where the host's reader finds it —
    // without it the first launch after an install spends seconds compiling.
    if (sources.bytecode && existsSync(sources.bytecode)) {
        await cp(sources.bytecode, path.join(assetsDir, path.basename(sources.bytecode)));
    }
    // So does a V8 host's startup snapshot, without which the engine cannot start.
    if (sources.v8Snapshots && existsSync(sources.v8Snapshots)) {
        await cp(sources.v8Snapshots, path.join(assetsDir, 'v8'), { recursive: true });
    }

    await cp(sources.libs, path.join(mainDir, 'jniLibs'), { recursive: true });
    // What the export built per ABI (the project's compiled systems), beside the template's.
    for (const [abi, files] of Object.entries(sources.extraLibs ?? {})) {
        if (!abis.includes(abi)) continue;
        for (const file of files) await cp(file, path.join(mainDir, 'jniLibs', abi, path.basename(file)));
    }
    if (existsSync(sources.java)) {
        await cp(sources.java, path.join(mainDir, 'java'), { recursive: true });
    }

    const manifest = gradleManifest(await readFile(sources.manifestIn, 'utf8'), app);
    await writeFile(path.join(mainDir, 'AndroidManifest.xml'), manifest.xml);

    const iconDir = path.join(mainDir, 'res', 'mipmap-xxxhdpi');
    await mkdir(iconDir, { recursive: true });
    await writeFile(path.join(iconDir, 'ic_launcher.png'), icon ?? await readFile(sources.icon));

    await writeIfAbsent(path.join(appDir, 'build.gradle.kts'), renderAppGradle({
        appId: app.id,
        version: app.version,
        versionCode: app.versionCode,
        minSdk: manifest.minSdk,
        targetSdk: manifest.targetSdk,
        abis,
    }));
    await writeIfAbsent(path.join(contentDir, 'settings.gradle.kts'), renderSettingsGradle(name));
    await writeIfAbsent(path.join(contentDir, 'build.gradle.kts'), renderRootGradle());
    await writeIfAbsent(path.join(contentDir, 'gradle.properties'), renderGradleProperties());
    await writeIfAbsent(path.join(contentDir, '.gitignore'), renderGitignore());
    await writeIfAbsent(path.join(contentDir, 'README.md'), renderProjectReadme({ name, abis }));

    return contentDir;
}

/** Write a file the user is expected to edit — once, and never over their copy. */
async function writeIfAbsent(file, contents) {
    if (existsSync(file)) return;
    await writeFile(file, contents);
}