@driftengine/package 4.13.1 → 4.13.3

package/README.md

@@ -59,7 +59,7 @@ Beside your `package.json`, in the project that produces the web build:
   "splash": { "show": true, "minMs": 1400 },
   "targets": ["linux-x64", "win-x64", "mac-arm64"],
   "steam": { "appId": null },
-  "android": { "permissions": [], "cleartextTraffic": false }
+  "android": { "permissions": [], "cleartextTraffic": false, "orientation": "unspecified" }
 }
 ```
 
@@ -280,6 +280,23 @@ renderer cannot disagree — which they would if only the manifest moved.
 Set it only for the case it exists for: a relay on a LAN, which cannot hold a certificate for an
 address that is not a name. A public relay should be `wss://` and this should stay false.
 
+### Which way the app is held
+
+`orientation` is the activity's `android:screenOrientation`, and it is `unspecified` by default,
+which leaves it to the phone. A game played sideways says so:
+
+```json
+"android": { "orientation": "sensorLandscape" }
+```
+
+Any value Android documents is accepted (`landscape`, `sensorLandscape`, `portrait`,
+`sensorPortrait`, `userLandscape`, `fullSensor` and the rest), and one it does not is refused when
+the manifest is read, since Android ignores an attribute value it does not know and the build would
+quietly be the phone's choice again. `sensorLandscape` lets a player turn the phone over;
+`landscape` does not. It is written into the copied manifest like the permissions, so the activity
+starts the right way round before any of the game's code runs, which a `lockOrientation` taken at
+run time cannot do.
+
 **Signing is not optional here and there is no unsigned option to offer**: Android refuses to
 install an unsigned APK at all. Without a keystore the packager generates one and says so on every
 build. That APK installs on a device with developer mode on; it cannot go to the Play Store.

package/dist/android.js

@@ -85,6 +85,9 @@ export async function buildAndroid(manifest, projectDir, outDir, options = {}) {
          */
         console.log('[drift-package] android: cleartext traffic permitted (http:// and ws:// allowed)');
     }
+    if (manifest.android.orientation !== 'unspecified') {
+        console.log(`[drift-package] android: held ${manifest.android.orientation}`);
+    }
     if (manifest.icon !== null) {
         /* One PNG at one density: Android scales it for the rest, and a game that wants a full set
            supplies its own `res/` through its own build rather than through this. */

package/dist/cli.js

@@ -115,6 +115,9 @@ async function doctor(cwd, options = {}) {
         console.log(`  android: cleartext ${manifest.android.cleartextTraffic
             ? 'permitted — http:// and ws:// are allowed, and mixed content with them'
             : 'refused — a relay must be wss://'}`);
+        console.log(`  android: orientation ${manifest.android.orientation === 'unspecified'
+            ? "unspecified — the phone's own choice"
+            : manifest.android.orientation}`);
     }
     /*
      * **What each target still needs, and the command that fetches it.** A `doctor` that only

package/dist/manifest.d.ts

@@ -1,3 +1,16 @@
+/**
+ * `drift.package.json`, parsed once and trusted afterwards.
+ *
+ * **Every rejection names its field.** A packaging manifest is written by hand, usually once, and
+ * a wrong value surfaces at signing or at first launch on a machine the author does not have. The
+ * cost of validating here is a few dozen lines; the cost of not validating is a build.
+ *
+ * **What is defaulted and what is not** is the only interesting decision in this file. Window size
+ * and features default, because a short manifest is easier to read and a wrong window is visible
+ * immediately. The id, the entry, the targets and the backend policy do not, because each of them
+ * is silent when wrong: the wrong id writes saves to a directory nobody looks in.
+ */
+import { type AndroidOrientation } from './mobile/androidManifest.ts';
 export type WebGpuPolicy = 'prefer' | 'require' | 'off';
 export type Target = 'win-x64' | 'mac-arm64' | 'mac-x64' | 'linux-x64' | 'native-linux-x64' | 'android' | 'ios';
 /** The two that are a phone rather than a desktop, and differ in almost every way that matters. */
@@ -49,10 +62,16 @@ export interface PackageManifest {
      * sets `android:usesCleartextTraffic` *and* is what `MainActivity` reads at runtime to allow
      * mixed content in the WebView, so the platform and the renderer cannot disagree about it. A
      * relay on a LAN cannot hold a certificate, which is the case it exists for.
+     *
+     * **`orientation` is `unspecified` by default**, which leaves it to the phone, and takes any
+     * value Android documents for an activity (`landscape`, `sensorLandscape`, `portrait`, ...). A
+     * game played sideways says so here, and the activity starts that way before any of its code
+     * runs; one Android does not know is refused rather than written.
      */
     readonly android: {
         readonly permissions: readonly string[];
         readonly cleartextTraffic: boolean;
+        readonly orientation: AndroidOrientation;
     };
     /**
      * Who an installer says this is from.

package/dist/manifest.js

@@ -10,7 +10,7 @@
  * immediately. The id, the entry, the targets and the backend policy do not, because each of them
  * is silent when wrong: the wrong id writes saves to a directory nobody looks in.
  */
-import { checkPermission, fullPermissionName } from './mobile/androidManifest.js';
+import { checkOrientation, checkPermission, fullPermissionName, } from './mobile/androidManifest.js';
 /** The two that are a phone rather than a desktop, and differ in almost every way that matters. */
 export const MOBILE_TARGETS = ['android', 'ios'];
 const POLICIES = ['prefer', 'require', 'off'];
@@ -117,6 +117,9 @@ export function parseManifest(raw) {
         android: {
             permissions,
             cleartextTraffic: androidRaw.cleartextTraffic === true,
+            orientation: androidRaw.orientation === undefined
+                ? 'unspecified'
+                : checkOrientation(androidRaw.orientation),
         },
         splash: {
             show: splashRaw.show !== false,

package/dist/mobile/androidManifest.d.ts

@@ -5,9 +5,24 @@ export interface AndroidOptions {
     readonly permissions: readonly string[];
     /** Whether the app may open `http://` and `ws://` at all. */
     readonly cleartextTraffic: boolean;
+    /** The activity's `android:screenOrientation`, one of `ANDROID_ORIENTATIONS`. */
+    readonly orientation: AndroidOrientation;
 }
+/**
+ * Every value Android documents for an activity's `android:screenOrientation`.
+ *
+ * **The whole list, not the two a landscape game wants**, because which way a game is held is the
+ * game's decision and the engine has no reason to prefer one: a card game is held upright, a
+ * racing game sideways, and `sensorLandscape` against `landscape` is whether a player may turn
+ * the phone over. What the list buys is a refusal at parse time, since the value is written into
+ * an XML attribute and Android answers one it does not know by ignoring it.
+ */
+export declare const ANDROID_ORIENTATIONS: readonly ['unspecified', 'behind', 'landscape', 'portrait', 'reverseLandscape', 'reversePortrait', 'sensorLandscape', 'sensorPortrait', 'userLandscape', 'userPortrait', 'sensor', 'fullSensor', 'nosensor', 'user', 'fullUser', 'locked'];
+export type AndroidOrientation = (typeof ANDROID_ORIENTATIONS)[number];
 /** Nothing asked for: what every build got before this existed, and still gets. */
 export declare const NO_ANDROID_OPTIONS: AndroidOptions;
+/** Refuse an orientation Android does not document, at parse time where a consumer can fix it. */
+export declare function checkOrientation(value: unknown): AndroidOrientation;
 /**
  * `INTERNET` and `android.permission.INTERNET` are the same thing, written two ways.
  *
@@ -20,7 +35,8 @@ export declare function fullPermissionName(name: string): string;
 /** Refuse a name that cannot go into the XML, at parse time where a consumer can fix it. */
 export declare function checkPermission(name: string): void;
 /**
- * The template manifest with a game's permissions in it, and its cleartext policy set.
+ * The template manifest with a game's permissions in it, its cleartext policy set, and its
+ * activity held the way the game asked.
  *
  * **Written into the copy, not into the template**, the way the icon already is: `buildAndroid`
  * stages `packages/package/android/` into `out/android/project` and edits it there, so this

package/dist/mobile/androidManifest.js

@@ -1,9 +1,46 @@
 /** What a game asks the Android manifest for, written into the copied template before Gradle runs. */
+/**
+ * Every value Android documents for an activity's `android:screenOrientation`.
+ *
+ * **The whole list, not the two a landscape game wants**, because which way a game is held is the
+ * game's decision and the engine has no reason to prefer one: a card game is held upright, a
+ * racing game sideways, and `sensorLandscape` against `landscape` is whether a player may turn
+ * the phone over. What the list buys is a refusal at parse time, since the value is written into
+ * an XML attribute and Android answers one it does not know by ignoring it.
+ */
+export const ANDROID_ORIENTATIONS = [
+    'unspecified',
+    'behind',
+    'landscape',
+    'portrait',
+    'reverseLandscape',
+    'reversePortrait',
+    'sensorLandscape',
+    'sensorPortrait',
+    'userLandscape',
+    'userPortrait',
+    'sensor',
+    'fullSensor',
+    'nosensor',
+    'user',
+    'fullUser',
+    'locked',
+];
 /** Nothing asked for: what every build got before this existed, and still gets. */
 export const NO_ANDROID_OPTIONS = Object.freeze({
     permissions: Object.freeze([]),
     cleartextTraffic: false,
+    orientation: 'unspecified',
 });
+/** Refuse an orientation Android does not document, at parse time where a consumer can fix it. */
+export function checkOrientation(value) {
+    const known = ANDROID_ORIENTATIONS.find((name) => name === value);
+    if (known === undefined) {
+        throw new Error(`drift.package.json: "android.orientation" is ${JSON.stringify(value)}, expected one of ` +
+            `${ANDROID_ORIENTATIONS.join(', ')}.`);
+    }
+    return known;
+}
 /**
  * `INTERNET` and `android.permission.INTERNET` are the same thing, written two ways.
  *
@@ -32,7 +69,8 @@ export function checkPermission(name) {
     }
 }
 /**
- * The template manifest with a game's permissions in it, and its cleartext policy set.
+ * The template manifest with a game's permissions in it, its cleartext policy set, and its
+ * activity held the way the game asked.
  *
  * **Written into the copy, not into the template**, the way the icon already is: `buildAndroid`
  * stages `packages/package/android/` into `out/android/project` and edits it there, so this
@@ -83,7 +121,19 @@ export function withAndroidManifest(xml, options) {
         throw new Error('the Android manifest template no longer declares android:usesCleartextTraffic, so asking ' +
             'for cleartext traffic would do nothing');
     }
-    return replaced;
+    /*
+     * **Rewritten on the activity for the same reason**: the template carries `unspecified`, which
+     * leaves the choice to the phone. Held by the manifest rather than by `lockOrientation` at run
+     * time, because the activity is laid out before any of the game's code runs, and a lock taken
+     * then turns a picture the player has already seen.
+     */
+    const oriented = replaced.replace(/android:screenOrientation="[A-Za-z]+"/, `android:screenOrientation="${options.orientation}"`);
+    if (!/android:screenOrientation="[A-Za-z]+"/.test(replaced) &&
+        options.orientation !== 'unspecified') {
+        throw new Error('the Android manifest template no longer declares android:screenOrientation, so asking for ' +
+            `"${options.orientation}" would do nothing`);
+    }
+    return oriented;
 }
 /** The whitespace at the start of the line `at` falls on, so an inserted element lines up. */
 function indentOf(xml, at) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/package",
-  "version": "4.13.1",
+  "version": "4.13.3",
   "description": "Builds an installable application from a game built on the engine",
   "license": "Apache-2.0",
   "type": "module",
@@ -49,7 +49,7 @@
     "drift-package": "bin/drift-package.mjs"
   },
   "peerDependencies": {
-    "@driftengine/core": "4.13.1",
+    "@driftengine/core": "4.13.3",
     "steamworks.js": ">=0.4.0"
   },
   "dependencies": {

package/src/android.ts

@@ -101,6 +101,9 @@ export async function buildAndroid(
      */
     console.log('[drift-package] android: cleartext traffic permitted (http:// and ws:// allowed)');
   }
+  if (manifest.android.orientation !== 'unspecified') {
+    console.log(`[drift-package] android: held ${manifest.android.orientation}`);
+  }
 
   if (manifest.icon !== null) {
     /* One PNG at one density: Android scales it for the rest, and a game that wants a full set

package/src/cli.ts

@@ -125,6 +125,13 @@ async function doctor(cwd: string, options: ResourceOptions = {}): Promise<Packa
           : 'refused — a relay must be wss://'
       }`,
     );
+    console.log(
+      `  android: orientation ${
+        manifest.android.orientation === 'unspecified'
+          ? "unspecified — the phone's own choice"
+          : manifest.android.orientation
+      }`,
+    );
   }
 
   /*

package/src/manifest.ts

@@ -10,7 +10,12 @@
  * immediately. The id, the entry, the targets and the backend policy do not, because each of them
  * is silent when wrong: the wrong id writes saves to a directory nobody looks in.
  */
-import { checkPermission, fullPermissionName } from './mobile/androidManifest.ts';
+import {
+  checkOrientation,
+  checkPermission,
+  fullPermissionName,
+  type AndroidOrientation,
+} from './mobile/androidManifest.ts';
 
 export type WebGpuPolicy = 'prefer' | 'require' | 'off';
 export type Target =
@@ -77,10 +82,16 @@ export interface PackageManifest {
    * sets `android:usesCleartextTraffic` *and* is what `MainActivity` reads at runtime to allow
    * mixed content in the WebView, so the platform and the renderer cannot disagree about it. A
    * relay on a LAN cannot hold a certificate, which is the case it exists for.
+   *
+   * **`orientation` is `unspecified` by default**, which leaves it to the phone, and takes any
+   * value Android documents for an activity (`landscape`, `sensorLandscape`, `portrait`, ...). A
+   * game played sideways says so here, and the activity starts that way before any of its code
+   * runs; one Android does not know is refused rather than written.
    */
   readonly android: {
     readonly permissions: readonly string[];
     readonly cleartextTraffic: boolean;
+    readonly orientation: AndroidOrientation;
   };
   /**
    * Who an installer says this is from.
@@ -202,6 +213,10 @@ export function parseManifest(raw: unknown): PackageManifest {
     android: {
       permissions,
       cleartextTraffic: androidRaw.cleartextTraffic === true,
+      orientation:
+        androidRaw.orientation === undefined
+          ? 'unspecified'
+          : checkOrientation(androidRaw.orientation),
     },
     splash: {
       show: splashRaw.show !== false,

package/src/mobile/androidManifest.ts

@@ -6,14 +6,59 @@ export interface AndroidOptions {
   readonly permissions: readonly string[];
   /** Whether the app may open `http://` and `ws://` at all. */
   readonly cleartextTraffic: boolean;
+  /** The activity's `android:screenOrientation`, one of `ANDROID_ORIENTATIONS`. */
+  readonly orientation: AndroidOrientation;
 }
 
+/**
+ * Every value Android documents for an activity's `android:screenOrientation`.
+ *
+ * **The whole list, not the two a landscape game wants**, because which way a game is held is the
+ * game's decision and the engine has no reason to prefer one: a card game is held upright, a
+ * racing game sideways, and `sensorLandscape` against `landscape` is whether a player may turn
+ * the phone over. What the list buys is a refusal at parse time, since the value is written into
+ * an XML attribute and Android answers one it does not know by ignoring it.
+ */
+export const ANDROID_ORIENTATIONS = [
+  'unspecified',
+  'behind',
+  'landscape',
+  'portrait',
+  'reverseLandscape',
+  'reversePortrait',
+  'sensorLandscape',
+  'sensorPortrait',
+  'userLandscape',
+  'userPortrait',
+  'sensor',
+  'fullSensor',
+  'nosensor',
+  'user',
+  'fullUser',
+  'locked',
+] as const;
+
+export type AndroidOrientation = (typeof ANDROID_ORIENTATIONS)[number];
+
 /** Nothing asked for: what every build got before this existed, and still gets. */
 export const NO_ANDROID_OPTIONS: AndroidOptions = Object.freeze({
   permissions: Object.freeze([]) as readonly string[],
   cleartextTraffic: false,
+  orientation: 'unspecified',
 });
 
+/** Refuse an orientation Android does not document, at parse time where a consumer can fix it. */
+export function checkOrientation(value: unknown): AndroidOrientation {
+  const known = ANDROID_ORIENTATIONS.find((name) => name === value);
+  if (known === undefined) {
+    throw new Error(
+      `drift.package.json: "android.orientation" is ${JSON.stringify(value)}, expected one of ` +
+        `${ANDROID_ORIENTATIONS.join(', ')}.`,
+    );
+  }
+  return known;
+}
+
 /**
  * `INTERNET` and `android.permission.INTERNET` are the same thing, written two ways.
  *
@@ -47,7 +92,8 @@ export function checkPermission(name: string): void {
 }
 
 /**
- * The template manifest with a game's permissions in it, and its cleartext policy set.
+ * The template manifest with a game's permissions in it, its cleartext policy set, and its
+ * activity held the way the game asked.
  *
  * **Written into the copy, not into the template**, the way the icon already is: `buildAndroid`
  * stages `packages/package/android/` into `out/android/project` and edits it there, so this
@@ -105,7 +151,27 @@ export function withAndroidManifest(xml: string, options: AndroidOptions): strin
         'for cleartext traffic would do nothing',
     );
   }
-  return replaced;
+
+  /*
+   * **Rewritten on the activity for the same reason**: the template carries `unspecified`, which
+   * leaves the choice to the phone. Held by the manifest rather than by `lockOrientation` at run
+   * time, because the activity is laid out before any of the game's code runs, and a lock taken
+   * then turns a picture the player has already seen.
+   */
+  const oriented = replaced.replace(
+    /android:screenOrientation="[A-Za-z]+"/,
+    `android:screenOrientation="${options.orientation}"`,
+  );
+  if (
+    !/android:screenOrientation="[A-Za-z]+"/.test(replaced) &&
+    options.orientation !== 'unspecified'
+  ) {
+    throw new Error(
+      'the Android manifest template no longer declares android:screenOrientation, so asking for ' +
+        `"${options.orientation}" would do nothing`,
+    );
+  }
+  return oriented;
 }
 
 /** The whitespace at the start of the line `at` falls on, so an inserted element lines up. */