kam-mobile/README.md

# KaM Remake Mobile

This repository is the Android development baseline for the KaM Remake r16020 port. Its upstream authority is KaM Remake r16020, commit `962fb850324b79bbe5480e1c2087d98f83a60917`. It is the permanent single-application build, source, and resource baseline for later port work; it is not yet a complete playable game.

## Build

The one supported entrypoint is:

```bash
./build-android.sh
```

Supported options are `--local`, `--cpu {aarch64,arm,x86_64}`, `--no-fetch`, and `--timeout <positive seconds>`.

- `--local` uses host tooling while keeping the Android target unchanged.
- `--cpu` selects an ABI for the same application identity.
- `--no-fetch` requires the pinned vendor source to already be present and verified.
- `--timeout` is the per-external-tool-invocation timeout.

Each build is one permanent Castle application transaction. Read `out/current/build.json` for its finalized state. On `PASS`, the current package is described by `out/current/package.json` and is at `out/current/kam-mobile.apk`.

`build/<build_id>/` is transient working state. Its useful logs are `build/<build_id>/logs/compile.log`, `build/<build_id>/logs/package.log`, and, when apksigner is available and invoked, `build/<build_id>/logs/signature.log`.

## Source and resources

Pinned vendor source is at `vendor/kam_remake`. Project-owned source adaptation and registration are centralized, in order, in `config/extra-paths.json` and `tools/source_resolution.py`. Do not edit generated working manifests for source paths. `code/` is the permanent project-owned application source root; Pascal units enter through normal dependency closure from `GameInitialize`.

Private runtime-resource contents live under `private-assets/`. `config/runtime-resources.json` owns selection and `tools/resource_staging.py` owns staging. Selected files preserve their exact relative paths into Castle data. Proprietary game contents are not committed to public Git, and this baseline neither converts nor repacks them.

The permanent application definition is `app/CastleEngineManifest.xml`: `kam_mobile`, `org.kammobile.kamremake`, and `GameInitialize`.

## Optional device helper

After a successful current build, optionally run:

```bash
python3 tools/device.py [--serial <device-serial>]
```

It validates the current metadata and APK, selects the authorized device, installs, and launches the application.

## Current versus historical state

`out/current/**` is the only current finalized application/package state. `reports/**` and `dist/**` are frozen Task-1 historical evidence; files named `LATEST` there are historical pointers, not current build or package locators. Do not use them when the current build is missing or failed.

## Repository structure

```text
app/             permanent application definition
code/            permanent project-owned application source
config/          source and runtime-resource owners
tools/           build, source-resolution, resource-staging, and device tools
private-assets/  private runtime-resource contents
vendor/          pinned vendor source
build/           generated transient working state
out/             generated current finalized state
reports/         frozen Task-1 history
dist/            frozen Task-1 history
```