feat: ship full and Asset Store addon variants

.github/workflows/build.yml

@@ -217,26 +217,37 @@ jobs:
         with:
           path: artifacts
 
-      - name: Pack Godot addon
+      - name: Pack full and Asset Store addons
         env:
           RUSTC_WRAPPER: sccache
         run: |
-          # Use staging directory to avoid deleting source addon files
-          mise exec -- cargo xtask pack \
-            --artifacts artifacts \
-            --output dist/addons/godot_cef \
-            --addon-src addons/godot_cef
-          mise exec -- cargo xtask validate --addon dist/addons/godot_cef
-          # Use dist as ZIP root so Asset Library installs into res://addons/godot_cef.
-          zip -r godot_cef.zip dist
-
-      - name: Upload packed addon
+          # Stage each variant independently; both ZIPs retain the existing dist/addons layout.
+          for variant in full store; do
+            mise exec -- cargo xtask pack \
+              --artifacts artifacts \
+              --output staging/$variant/dist/addons/godot_cef \
+              --addon-src addons/godot_cef \
+              --variant "$variant"
+            mise exec -- cargo xtask validate \
+              --addon staging/$variant/dist/addons/godot_cef --variant "$variant"
+          done
+          (cd staging/full && zip -r ../../godot_cef.zip dist)
+          (cd staging/store && zip -r ../../godot_cef-store.zip dist)
+
+      - name: Upload full addon
         uses: actions/upload-artifact@v7
         with:
           name: godot_cef-addon
           path: godot_cef.zip
           retention-days: 30
 
+      - name: Upload Asset Store addon
+        uses: actions/upload-artifact@v7
+        with:
+          name: godot_cef-store-addon
+          path: godot_cef-store.zip
+          retention-days: 30
+
   release:
     needs: [pack]
     runs-on: ubuntu-latest
@@ -253,8 +264,16 @@ jobs:
           name: godot_cef-addon
           path: .
 
-      - name: Rename addon with version
-        run: mv godot_cef.zip godot_cef-${{ github.ref_name }}.zip
+      - name: Download Asset Store addon
+        uses: actions/download-artifact@v8
+        with:
+          name: godot_cef-store-addon
+          path: .
+
+      - name: Rename addons with version
+        run: |
+          mv godot_cef.zip godot_cef-${{ github.ref_name }}.zip
+          mv godot_cef-store.zip godot_cef-store-${{ github.ref_name }}.zip
 
       - name: Create GitHub Release
         uses: softprops/action-gh-release@v3
@@ -263,4 +282,6 @@ jobs:
           draft: true # release is draft until it is manually published
           prerelease: ${{ contains(github.ref_name, '-') }}
           generate_release_notes: true
-          files: godot_cef-${{ github.ref_name }}.zip
+          files: |
+            godot_cef-${{ github.ref_name }}.zip
+            godot_cef-store-${{ github.ref_name }}.zip

CONTRIBUTING.md

@@ -295,6 +295,26 @@ For release or packaging changes, also run `cargo xtask pack` with the
 platform artifacts you changed and then `cargo xtask validate --addon` against
 the staged addon directory.
 
+### Distribution variants
+
+`cargo xtask pack` defaults to the full addon, preserving all five platform
+artifacts. For release packaging, stage and validate each variant independently:
+
+```bash
+cargo xtask pack --artifacts artifacts --output staging/full/dist/addons/godot_cef --variant full
+cargo xtask validate --addon staging/full/dist/addons/godot_cef --variant full
+cargo xtask pack --artifacts artifacts --output staging/store/dist/addons/godot_cef --variant store
+cargo xtask validate --addon staging/store/dist/addons/godot_cef --variant store
+```
+
+Variant validation requires every selected target and rejects excluded target
+directories. Omit `--variant` for the existing partial-addon validation behavior.
+The Store packer derives its descriptor from the full source manifest by removing
+Windows/Linux ARM64 entries; do not install both descriptors in one Godot project.
+See [Distribution variants](docs/api/distribution-variants.md) for archive layout,
+architecture coverage, and manual ARM64 builds. CI builds all architectures and
+publishes both package artifacts; this PR does not itself publish a release.
+
 ### Lifecycle Cleanup Checklist
 
 When changing browser lifecycle code, preserve these cleanup invariants for `CefTexture`:

README.md

@@ -92,6 +92,14 @@ For comprehensive API documentation, examples, and guides, visit the [full docum
 
 ## Platform Support
 
+The default/full GitHub Release addon includes Windows x86_64/ARM64, Linux
+x86_64/ARM64, and macOS universal (x86_64/ARM64). A separate **Asset Store** addon
+includes Windows x86_64, Linux x86_64, and the same macOS universal framework to
+reduce download size. Both packages install as `addons/godot_cef`; choose one.
+ARM64 Windows/Linux users should use the full package. See
+[Distribution variants](https://godotcef.org/api/distribution-variants.html) for
+package names, local packaging commands and source-build instructions.
+
 | Platform | DirectX 12 | Metal | Vulkan | Software Rendering |
 |----------|------------|-------|--------|-------------------|
 | **Windows** | ✅ (Note 1) | n.a. | ✅ (Note 2) | ✅ |

docs/.vitepress/config.mts

@@ -51,6 +51,7 @@ export default withMermaid(defineConfig({
                 { text: '拖放', link: '/zh_CN/api/drag-and-drop' },
                 { text: '下载', link: '/zh_CN/api/downloads' },
                 { text: 'Vulkan 支持', link: '/zh_CN/api/vulkan-support' },
+                { text: '分发版本与源码构建', link: '/zh_CN/api/distribution-variants' },
                 { text: 'GPU 设备绑定', link: '/zh_CN/api/gpu-device-pinning' }
               ]
             }
@@ -99,6 +100,7 @@ export default withMermaid(defineConfig({
             { text: 'Drag and Drop', link: '/api/drag-and-drop' },
             { text: 'Downloads', link: '/api/downloads' },
             { text: 'Vulkan Support', link: '/api/vulkan-support' },
+            { text: 'Distribution Variants', link: '/api/distribution-variants' },
             { text: 'GPU Device Pinning', link: '/api/gpu-device-pinning' }
           ]
         }

docs/api/compatibility-matrix.md

@@ -2,6 +2,10 @@
 
 This matrix summarizes the expected rendering mode behavior for each platform/backend combination.
 
+This page covers architectures in the full GitHub Release addon. The smaller
+Asset Store addon omits Windows/Linux ARM64; use the full package for those
+targets. See [Distribution variants](./distribution-variants).
+
 ## Version Baseline
 
 Current builds are based on the Rust `cef` / `cef-dll-sys` crates resolved as `152.3.0+152.0.6` in `Cargo.lock`. The matching CEF runtime version is pinned as `CEF_VERSION` in `mise.toml`; use it when installing CEF binaries manually:

docs/api/distribution-variants.md

@@ -0,0 +1,178 @@
+---
+title: Distribution Variants
+description: Choose the full GitHub Release or smaller Asset Store addon and build custom ARM64 binaries.
+---
+
+# Distribution variants
+
+Godot CEF builds every supported architecture and produces two distribution
+packages to address the Asset Store size limit. The full package continues to
+provide Windows/Linux ARM64 binaries. This approach preserves platform support
+and the default full-package behavior. See [#238](https://github.com/dsh0416/godot-cef/issues/238)
+and [#239](https://github.com/dsh0416/godot-cef/pull/239) for the discussion.
+
+| Package | Release filename | Platform directories |
+|---|---|---|
+| Full (default) | `godot_cef-v<version>.zip` | Windows x86_64/ARM64, Linux x86_64/ARM64, macOS universal |
+| Asset Store | `godot_cef-store-v<version>.zip` | Windows x86_64, Linux x86_64, macOS universal |
+
+macOS universal always includes x86_64 and ARM64. CI uploads separate ZIP
+artifacts named `godot_cef-addon` and `godot_cef-store-addon`. The tag release
+workflow attaches both to a draft release; PR builds do not publish releases.
+
+## Choose or switch packages
+
+Use the **full package** for native Windows/Linux ARM64 Godot editors or exports.
+The Store package has no registrations for those architectures, so native ARM64
+processes cannot load the extension from it. Windows x86_64 emulation is not a
+replacement validated by this change.
+
+Both ZIPs preserve the existing `dist/addons/godot_cef/` archive layout and install
+as `addons/godot_cef/` in the project. Each package contains one
+`godot_cef.gdextension` descriptor whose registrations match its binaries.
+Back up local changes and **replace the whole addon directory** when switching
+packages instead of extracting over an older installation. Do not install both
+addon copies or descriptors together, as they register the same extension classes.
+
+The full descriptor comes from `addons/godot_cef/godot_cef.gdextension` in the
+repository. The Store packer automatically removes Windows/Linux ARM64 library
+entries and dependency dictionaries and does not copy those architecture
+artifacts. Both packages share a version and API; architecture coverage differs.
+Measure the final ZIP size from the actual build: a smaller target set does not
+by itself confirm compliance with the Asset Store's exact byte limit.
+
+## Generate both packages locally
+
+Inputs use `artifacts/gdcef-<target>/`, containing the extension, helper and CEF
+runtime assets for that target. `cargo xtask pack` defaults to `full`, preserving
+existing behavior; the Store variant is explicit. From the repository root with
+the mise environment active:
+
+```bash
+cargo xtask pack --artifacts artifacts --output staging/full/dist/addons/godot_cef --variant full
+cargo xtask validate --addon staging/full/dist/addons/godot_cef --variant full
+cargo xtask pack --artifacts artifacts --output staging/store/dist/addons/godot_cef --variant store
+cargo xtask validate --addon staging/store/dist/addons/godot_cef --variant store
+(cd staging/full && zip -r ../../godot_cef.zip dist)
+(cd staging/store && zip -r ../../godot_cef-store.zip dist)
+```
+
+The input targets are `universal-apple-darwin`, `x86_64-pc-windows-msvc`,
+`aarch64-pc-windows-msvc`, `x86_64-unknown-linux-gnu`, and
+`aarch64-unknown-linux-gnu`. `validate --variant` requires every selected target
+and rejects excluded target directories. Omitting `--variant` preserves the
+existing partial-addon validation behavior. Packing recreates the output
+folder; stage separately and do not use the source addon directory as output.
+
+## Custom ARM64 source builds
+
+Most users can choose the full prebuilt package. If you need to maintain your own
+build, the existing source entry points are shown below. These commands were
+reviewed against current build inputs and runtime layout; local verification did
+not compile ARM64 binaries or run an ARM64 editor/rendering/export. Full platform
+builds are checked by PR CI. You must still verify compiler/runtime availability
+and compatibility with the destination system.
+
+## Common prerequisites
+
+Use a clean checkout of the exact tag or commit you intend to maintain. Install
+Git and mise, then run commands from the repository root. `mise install` provides
+the Rust nightly and `export-cef-dir` pinned by `mise.toml`. Use that checkout's
+`CEF_VERSION`, not an arbitrary newer CEF runtime. A C++ compiler, CMake, and
+Godot 4.5+ for the target OS/architecture are also required. Builds can consume
+substantial disk space and memory.
+
+`cargo xtask bundle` dispatches by the **host OS**: use Windows for Windows
+builds and Linux for Linux builds. Passing a Windows/Linux target on macOS does
+not provide a cross-OS build path.
+
+## Windows ARM64 from a Windows x64 host
+
+Install Visual Studio 2022 Build Tools with Desktop development with C++, the
+MSVC ARM64 build tools and a Windows SDK. Use a Developer Command Prompt configured
+for x64-host/ARM64-target (`amd64_arm64`). For example, in `cmd.exe`, replace the
+installation path with your actual Visual Studio location, then launch PowerShell
+from that configured prompt so it inherits the compiler environment:
+
+```bat
+call "<Visual Studio installation>\VC\Auxiliary\Build\vcvarsall.bat" amd64_arm64
+pwsh -NoProfile
+```
+
+Install CMake and PowerShell 7 (`pwsh`) and make them available on `PATH`. Run:
+
+```powershell
+mise trust
+mise install
+mise exec -- pwsh -NoProfile
+# The following commands run inside this mise environment.
+$env:CEF_PATH = "$env:USERPROFILE/.local/share/cef_windows_arm64"
+export-cef-dir --version $env:CEF_VERSION --target aarch64-pc-windows-msvc --force $env:CEF_PATH
+rustup target add aarch64-pc-windows-msvc
+cargo xtask bundle --release --target aarch64-pc-windows-msvc
+```
+
+Do not point `CEF_PATH` at an x64 runtime. The bundled output includes the helper,
+DLLs, locales and CEF resources, and is deployed to
+`addons/godot_cef/bin/aarch64-pc-windows-msvc/`. Cargo's target build output is
+`target/aarch64-pc-windows-msvc/release/` with the default target directory.
+A native Windows ARM64 host requires an ARM64-host/ARM64-target developer
+environment and matching native tools; that host setup is not validated here.
+
+## Linux ARM64 from a Linux x64 host
+
+For a Debian/Ubuntu-style host, install the ordinary build dependencies and the
+ARM64 cross compiler/binutils:
+
+```bash
+sudo apt-get update
+sudo apt-get install -y build-essential cmake libgtk-3-dev libnss3-dev \
+  libatk1.0-dev libatk-bridge2.0-dev libcups2-dev libdrm-dev \
+  libxkbcommon-dev libxcomposite-dev libxdamage-dev libxrandr-dev \
+  libgbm-dev libpango1.0-dev libasound2-dev \
+  gcc-aarch64-linux-gnu g++-aarch64-linux-gnu binutils-aarch64-linux-gnu
+mise trust
+mise install
+mise exec -- bash
+# The following commands run inside this mise environment.
+export CEF_PATH="$HOME/.local/share/cef_linux_arm64"
+export CC_aarch64_unknown_linux_gnu=aarch64-linux-gnu-gcc
+export CXX_aarch64_unknown_linux_gnu=aarch64-linux-gnu-g++
+export-cef-dir --version "$CEF_VERSION" --target aarch64-unknown-linux-gnu --force "$CEF_PATH"
+rustup target add aarch64-unknown-linux-gnu
+cargo xtask bundle --release --target aarch64-unknown-linux-gnu
+```
+
+The repository's `.cargo/config.toml` selects `aarch64-linux-gnu-gcc` and permits
+unresolved dependencies from `libcef.so` during cross linking. Those libraries
+must still exist on the target system. Host development packages alone do not
+supply an ARM64 runtime/sysroot; install target-architecture dependencies or
+configure a compatible ARM64 sysroot if required by the compiler or CEF build.
+Check the CEF runtime's glibc/system-library requirements against the destination.
+
+The Linux bundler uses `aarch64-linux-gnu-strip`, copies runtime assets and deploys
+to `addons/godot_cef/bin/aarch64-unknown-linux-gnu/`. Cargo's default target output
+is `target/aarch64-unknown-linux-gnu/release/`. A native Linux ARM64 build is also
+accepted, but the current linker/strip configuration still requires the named
+`aarch64-linux-gnu-*` tools; adjust your local toolchain if your distribution uses
+other names. No native ARM64 host setup is validated here.
+
+## Install and validate a custom build
+
+`cargo xtask bundle` deploys the complete runtime to the repository's
+`addons/godot_cef/bin/<target>/`. Copy the whole `addons/godot_cef/` into the project,
+or copy the target directory into a full addon from the same commit. The full
+repository descriptor already registers Windows/Linux ARM64; no manual manifest
+entries are needed. If you previously used a Store package, switch to the full
+descriptor and ensure its referenced target files match your deployed contents.
+Do not copy only the extension DLL/SO without dependencies, or enable two
+`.gdextension` descriptors together. Preserve Linux helper and `chrome-sandbox`
+executable permissions.
+
+On the ARM64 destination, verify native Godot editor and exported-game extension
+loading, helper startup, page rendering/input and exported runtime dependencies.
+On Linux, run `ldd` on `libgdcef.so`, `gdcef_helper` and `libcef.so` on that
+ARM64 system. Windows needs the matching MSVC runtime and CEF dependencies.
+Cross-compilation success does not guarantee editor/export runtime compatibility.
+Windows/Linux Vulkan hook acceleration still requires x86_64; start ARM64 runtime
+validation with software rendering; see [Vulkan support](./vulkan-support).

docs/api/vulkan-support.md

@@ -2,6 +2,10 @@
 
 This page documents how Godot CEF enables GPU-accelerated rendering on Vulkan backends through runtime function hooking, and the limitations of this approach.
 
+This page covers architectures in the full GitHub Release addon. The smaller
+Asset Store addon omits Windows/Linux ARM64; use the full package for those
+targets. See [Distribution variants](./distribution-variants).
+
 ## Background
 
 GPU-accelerated offscreen rendering (OSR) in CEF requires sharing textures between the CEF renderer process and the host application (Godot). This is achieved through platform-specific external memory APIs:
@@ -103,7 +107,7 @@ Vulkan hook-based acceleration is **only available on x86_64 (64-bit x86) archit
 The hooking mechanism relies on the [retour](https://github.com/darfink/retour-rs) library for runtime function detouring. This library currently does not support ARM64 architecture, which means:
 
 - **Windows ARM64** — Vulkan hooks not available
-- **Linux ARM64** — Vulkan hooks not available  
+- **Linux ARM64** — Vulkan hooks not available
 - **macOS (Apple Silicon)** — Vulkan hooks not available
 
 On unsupported architectures, the extension automatically falls back to software rendering.

docs/zh_CN/api/compatibility-matrix.md

@@ -2,6 +2,9 @@
 
 该矩阵用于总结不同平台与渲染后端下，Godot CEF 的预期渲染行为。
 
+本页包含完整 GitHub Release 包支持的架构。精简的 Asset Store 包不含 Windows/Linux ARM64；
+需要这些架构时请选择完整包。详见[分发版本](./distribution-variants)。
+
 ## 版本基线
 
 当前构建基于 `Cargo.lock` 中解析到的 Rust `cef` / `cef-dll-sys` crate 版本：`152.3.0+152.0.6`。匹配的 CEF 运行时版本已在 `mise.toml` 中固定为 `CEF_VERSION`；手动安装 CEF 二进制文件时请使用它：