|
| 1 | +--- |
| 2 | +name: maafw-template-migration |
| 3 | +description: Migrate a legacy MaaFramework project to the create-maa-project scaffold. Use when moving an old MAA-style project with assets/ + deps/ structure and install_*.py CI scripts to the CMP template (maa-project.json, build-release.mjs, sync-runtime.mjs). |
| 4 | +--- |
| 5 | + |
| 6 | +# MaaFramework Project Template Migration |
| 7 | + |
| 8 | +Guide for migrating legacy MaaFW projects to the create-maa-project (CMP) scaffold. |
| 9 | + |
| 10 | +## When to use |
| 11 | + |
| 12 | +- Old project has `assets/` (resource + interface.json), `deps/` (MaaFramework binaries), `install*.py` (packaging scripts, possibly under `tools/` or `tools/ci/`) |
| 13 | +- Moving to CMP's `maa-project.json` + `tools/build-release.mjs` + `tools/sync-runtime.mjs` |
| 14 | + |
| 15 | +## Migration workflow |
| 16 | + |
| 17 | +### 1. Scaffold a fresh CMP project |
| 18 | + |
| 19 | +In a new directory, run CMP to generate a clean project skeleton: |
| 20 | + |
| 21 | +```bash |
| 22 | +pnpm dlx create-maa-project@latest |
| 23 | +``` |
| 24 | + |
| 25 | +Select template (agent or pipeline-only), GUI types, OCR source, etc. This generates `maa-project.json`, `interface.json`, `tools/build-release.mjs`, `tools/sync-runtime.mjs`, `.github/workflows/release.yml`, `package.json`, `.gitignore`, and other boilerplate. Keep these generated files as the base — do not overwrite them with old project files. |
| 26 | + |
| 27 | +### 2. Migrate old content into the scaffolded structure |
| 28 | + |
| 29 | +Bring over only project-specific content from the old project: |
| 30 | + |
| 31 | +| Old | New | Notes | |
| 32 | +|---|---|---| |
| 33 | +| `assets/resource/` | `resource/base/` | Drop `assets/`, rename `resource` to `base` | |
| 34 | +| `assets/resource_bilibili/` | `resource/bilibili/` | Same pattern for each variant | |
| 35 | +| `assets/interface.json` | `interface.json` (root) | Overwrite the CMP-generated one, but keep the `version` field CMP added | |
| 36 | +| `tasks/` | `tasks/` | Usually direct copy | |
| 37 | +| Old agent code | `agent/` | If using agent template; update hardcoded paths | |
| 38 | + |
| 39 | +### 3. Configure maa-project.json |
| 40 | + |
| 41 | +Fill in project-specific settings: GUI types and channels, resource packs, controllers, OCR source, Python version. CMP generates a template but it needs real values. |
| 42 | + |
| 43 | +### 4. Extract non-MaaFW-bundle content from resource |
| 44 | + |
| 45 | +Old projects often keep everything under `resource/` — images, pipeline JSON, AND hot-update data. In the new structure, anything that is not part of the MaaFW bundle (images, models, pipeline) should be pulled out of `resource/`. For example, if old `resource/data/` contains hot-update data, it moves to top-level `data/`. Whether this data involves manifest caching depends on the project — CMP does not assume either way. |
| 46 | + |
| 47 | +### 5. Clean up obsolete paths |
| 48 | + |
| 49 | +- `deps/` directory: MaaFramework runtime binaries are now downloaded by `sync:runtime` — `deps/` is not needed |
| 50 | +- Old `install*.py` scripts: replaced by `tools/build-release.mjs` |
| 51 | +- `assets/` wrapper: gone, content moved to root-level directories |
| 52 | + |
| 53 | +## OCR models |
| 54 | + |
| 55 | +If using MaaCommonAssets submodule for OCR, `resource/base/model/ocr/` is generated by `sync:runtime` and should be gitignored. If managing OCR models manually (committed files), do not gitignore. |
| 56 | + |
| 57 | +## Agent code path updates |
| 58 | + |
| 59 | +If the project has a Python agent, check for hardcoded paths after migration: |
| 60 | + |
| 61 | +- Any `assets/` references in agent code need updating to new layout |
| 62 | +- If data moved out of `resource/`, update paths in `runtime_paths.py` or equivalent |
| 63 | +- `bootstrap.py` Python version check must match `pyproject.toml` `requires-python` |
| 64 | + |
| 65 | +## interface.json |
| 66 | + |
| 67 | +- Keep the `"version"` field (CMP adds it, build-release requires it) |
| 68 | +- CMP does not manage this file — controller/resource entries must match `maa-project.json` manually (lint warns but allows drift) |
| 69 | + |
| 70 | +## Common pitfalls |
| 71 | + |
| 72 | +1. **ocr.files key order**: CMP expects `{"destName": "srcRel"}` (destination filename to source path within submodule). Inverted = ENOENT on sync. Only relevant if `ocr.source = "submodule"`. |
| 73 | +2. **logo.ico not in git**: if the release workflow checks `hashFiles('logo.ico')`, the ico file must be committed — a generated or gitignored ico will cause the icon step to be silently skipped. |
| 74 | +3. **macOS bash 3.2**: GitHub macOS runners use bash 3.2 — no `${var^^}`, use `tr a-z A-Z` for uppercase in workflow scripts. |
| 75 | +4. **CMP version pinning**: `pnpm dlx create-maa-project@latest` may resolve to a stale version; pin in `pnpm-workspace.yaml` `minimumReleaseAgeExclude`. |
| 76 | + |
| 77 | +## Backporting to create-maa-project |
| 78 | + |
| 79 | +Generic fixes discovered during migration should be backported to CMP templates. Project-specific logic (private module downloads, specific mirrorchyan_rid values, manifest cache generation) stays in the project repo. |
0 commit comments