From 0fb159149b73a599351130ea0f92d409993f19e0 Mon Sep 17 00:00:00 2001 From: ienaga Date: Thu, 24 Sep 2026 22:05:19 +0900 Subject: [PATCH 1/3] =?UTF-8?q?Steam=E3=81=AE=E3=83=89=E3=82=AD=E3=83=A5?= =?UTF-8?q?=E3=83=A1=E3=83=B3=E3=83=88=E3=82=92=E6=9B=B4=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/steam.md | 681 +++++++++++++------------------------------------- 1 file changed, 174 insertions(+), 507 deletions(-) diff --git a/docs/steam.md b/docs/steam.md index 90bb47f..8989ec9 100644 --- a/docs/steam.md +++ b/docs/steam.md @@ -4,69 +4,42 @@ ## 日本語 -ローカルへの書き出しだけなら、Steamworks・SteamCMD・配布用の署名認証は不要。 +ローカル書き出しはSTEP1・3・5を実施する。Steam配布時は全STEPが必要。 -### STEP1：対象OSの実行環境とアイコンを用意する +### STEP1：環境・アイコンを用意する -- macOSのUniversalアプリと配布用の署名・公証はmacOS上で行う。 -- Next2D Frameworkのテンプレートの `src/assets/icons/` にWindows用ICO、macOS用ICNS、Linux用PNGを用意する。 - テンプレートの仮アイコンは配布前に差し替える。設定の省略時の扱いはSTEP3の表を参照。 +macOSのUniversal書き出し・署名・公証はmacOSで実行する。 +テンプレートの `src/assets/icons/` の仮アイコンを、Windows用ICO・macOS用ICNS・Linux用PNGに差し替える。 -#### 対応OS・CPU - -| OS | 既定値 | `architectures` / `--arch` の対応値 | +| OS | 既定CPU | `architectures` / `--arch` の対応値 | |---|---|---| | Windows | `x64` | `x64`, `arm64` | | macOS | `universal` | `x64`, `arm64`, `universal` | | Linux | `x64` | `x64`, `arm64` | -### STEP2：SteamworksのApp・Depot・テスト用ブランチを用意する（Steam配布時） - -1. 対象アプリのSteamworks管理画面で、発行済みのApp IDを確認する。 -2. SteamPipe > DepotsでDepotを作成し、対象OSを設定する。言語共通ならAll languagesを選び、 - Save Changesで保存後、公開（Publish）タブで変更を反映する。 - 開発用・テスト用・販売用Packageにも必要なDepotを含める。**Depot IDはApp IDから推測せず、実際の値を使う。** -3. SteamPipe > Buildsで `internal` ブランチを作成し、**パスワードを設定して関係者だけに共有する。** - 名前だけでは非公開にならず、builderはブランチ作成・パスワード設定や確認を行わない。 -4. テスターにゲームと対象Depotの利用権を用意する。未発売ゲームの外部テスターには - Release State Override（beta）キー等を使う。ブランチのパスワードだけでは利用権は付与されない。 - パスワードを第三者に共有しないよう運用し、JSONやリポジトリにも保存しない。 - -#### 複数Depotの構成とbuilderの対応範囲 +### STEP2：Steamworksを設定する -**Steamでは1つのApp IDに複数Depotを設定できる。** OS固有ファイルはOS別Depotに分ける構成をValveが推奨している。 - -| 構成 | Steam | 現在のbuilder | -|---|---|---| -| Windows / macOS / Linuxを別Depotにする | 対応。各Depotの対象OSを指定する。 | 対応。`steam.depots` の各OSに異なる発行済みIDを設定する。 | -| 複数OSを1つのDepotにまとめる | 対応。対象OSをAll OSesなど構成に合わせる。 | 対応。対象OSに同じIDを設定する。各OSのファイルをサブディレクトリに分ける。全対象OSのファイルを配布するため容量が増える。 | -| 一部OSだけ同じDepotにする | 対応。 | 対応。共有するOSだけ同じIDにする。 | -| 同じOS向けに本体・共通アセット・言語などを複数Depotに分ける | 対応。複数Depotの内容をインストール時に組み合わせる。 | 未対応。各OSの値は単一のDepot IDで、配列や追加アセット用キーには対応しない。 | +1. 発行済みApp IDを確認する。 +2. SteamPipe > DepotsでDepotを作成し、対象OS・言語を設定する。保存後、公開（Publish）タブで反映する。 +3. 開発用・テスト用・販売用の該当Packageに必要なDepotを含める。 +4. SteamPipe > Buildsで `internal` ブランチを作成し、パスワードを設定する。 +5. テスターにゲーム・Depotの利用権とブランチのパスワードを渡す。未発売ゲームの外部テストにはRelease State Overrideキー等を使う。 -builderの設定可能数は各OSに1 ID、全体で最大3つの異なるID。この上限はbuilderの設定形式によるもので、Steamの上限ではない。 -OSごとの成果物を揃える手順と起動パスはSTEP5、複数Depotを1回でアップロードする手順はSTEP6を参照する。 +**パスワードだけではゲームの利用権は付与されない。** builderはブランチ作成やパスワード設定を行わない。 -Steam側のダウンロード対象はPackageの利用権とDepotのOS・言語などの条件で決まる。 -同時にインストールするDepotで同じパスが重なると、Depot一覧の後にあるものが優先されるため、ファイルの配置を確認する。 -これらの選択条件はSteamworks側で設定し、builderのJSONからは反映しない。 +| Depot構成 | 設定 | +|---|---| +| OS別（Valve推奨） | OSごとに異なる発行済みDepot IDを指定する。 | +| 複数OSで共用 | 同じIDを指定し、Steamworksの対象OSをAll OSesなどに合わせる。全対象OSのファイルを配布する。 | -`internal` / `beta` はAppのビルドを選ぶブランチで、ブランチごとに別Depotを作る必要はない。 -また、この文書の「共有Depot」は同一App内で複数OSをまとめる意味。 -Steamworksの「Add Shared Depot」は別AppのDepotを参照する機能であり、builderの同一ID指定とは別の操作。 +Steamは複数Depotに対応。builderは各OSに1 IDまでで、一部OSだけの共用も可能。 +同一OSを複数Depotへ分割する構成は未対応。ブランチごとにDepotを作る必要はない。 -[Depotの設定](https://partner.steamgames.com/doc/store/application/depots) / -[Packageと利用権](https://partner.steamgames.com/doc/store/application/packages) / -[複数Depotのアップロード](https://partner.steamgames.com/doc/sdk/uploading) / -[betaブランチ](https://partner.steamgames.com/doc/store/application/branches) / -[Steamでのテスト](https://partner.steamgames.com/doc/store/testing) / -[Release State Overrideキー](https://partner.steamgames.com/doc/features/keys) +公式：[Depot](https://partner.steamgames.com/doc/store/application/depots) / [Package](https://partner.steamgames.com/doc/store/application/packages) / [テストと利用権](https://partner.steamgames.com/doc/store/testing) ### STEP3：electron.config.jsonを設定する -プロジェクトルートの `electron.config.json` でゲーム固有設定を管理する。 -JavaScript / TypeScriptの両テンプレートに含まれるので、初期値を自分のゲームの値に変更する。 -`appId` は macOS bundle ID・保存先識別子、`steam.appId` は Valve の数値 App ID。 -これらは別のID。バージョンはゲームルートの `package.json` を使う。 +ゲームルートの設定を変更する。バージョンはルートの `package.json` を使う。 ```json { @@ -90,62 +63,44 @@ JavaScript / TypeScriptの両テンプレートに含まれるので、初期値 } ``` -| 項目 | 用途・仕様 | 省略時・注意点 | -|---|---|---| -| `companyName` | Windows実行ファイルの会社名。 | 省略時は `package.json` の `author.name`、なければゲーム名。 | -| `appName` / `executableName` | `appName` はウィンドウ・アプリケーション名。`executableName` は実行ファイル名。 | 表示名と実行ファイル名を個別に設定できる。 | -| `description` | 任意の説明文。生成するElectronホストの `package.json` とWindowsのファイル説明に反映する。 | JSONの値を優先。未指定または `null` ならルートの `package.json` の `description` を使う。両方未指定なら空文字。明示的な `""` も空文字として扱う。 | -| `icons` | アイコン画像のパス。プロジェクトルートからの相対パス、または絶対パスを指定する。WindowsはICO、macOSはICNS、LinuxはPNG。 | 各キーは省略可。省略したOSにはbuilder同梱の仮のNext2Dアイコンを使う。`"icons": {}` なら全OSで仮アイコンを使える。指定したファイルがなければ失敗する。 | -| `architectures` | OSごとのCPU設定。対応値はSTEP1の「対応OS・CPU」を参照。 | 省略時はWindows/Linuxが `x64`、macOSが `universal`。`--arch` が優先する。 | -| `steam.appId` | Valveの数値App ID。未発行なら `null` を指定する。 | 未発行でもローカル書き出しは可能。SteamPipe用VDFは生成しない。 | -| `steam.branch` | `--steam-upload` の反映先betaブランチ。 | 省略時は `internal`。`--steam-branch` が優先する。ブランチの作成・パスワード設定はSteamworks側で行う。 | -| `steam.depots` | Steamworksで作成した実際のDepot ID。複数OSに同じIDを指定すると、同一Depotへまとめて配布する。 | App IDから推測しない。`null` / 未指定ならアプリと起動情報だけを生成し、アップロード用VDFは生成しない。 | -| `macos` | macOSアプリの署名・公証設定。 | ローカル検証用は `sign` / `notarize` ともに `false`。本番配布では両方を有効化する。 | - -### STEP4：署名・アップロードの認証を用意する（配布時） +| 項目 | 設定・確認事項 | +|---|---| +| `appId` | bundle ID・保存先識別子。Steam App IDとは別。配布前に自分の値へ変更する。 | +| `appName` / `executableName` | アプリ表示名 / 実行ファイル名。 | +| `companyName` | Windowsの会社名。省略時は `package.json` の `author.name`、なければゲーム名。 | +| `description` | 任意。未指定・`null` は `package.json` の説明を使用。 | +| `icons` | ゲームルートからの相対パスまたは絶対パス。省略したOSは仮アイコン、指定ファイルがなければ失敗。 | +| `architectures` | STEP1のCPU設定。`--arch` が優先。 | +| `steam.appId` / `steam.depots` | 配布時は `null` を実際のApp ID・Depot IDへ変更する。Depot IDをApp IDから推測しない。未設定のOSはアップロード対象外。 | +| `steam.branch` | 反映先。既定は `internal`。 | +| `macos.sign` / `macos.notarize` | ローカル検証は `false`、配布時は両方 `true`。 | + +### STEP4：認証を用意する #### macOSの署名・公証 -macOSのキーチェーンにDeveloper ID Application証明書と対応する秘密鍵を登録し、 -`xcrun notarytool store-credentials` で公証用プロファイルを保存する。認証情報はJSONへ書かない。 - -`APPLE_SIGNING_IDENTITY` に指定する署名IDは、次のコマンドで確認できる。 +キーチェーンに **Developer ID Application証明書と秘密鍵** を登録し、署名IDを確認する。 ```sh security find-identity -v -p codesigning ``` -表示された有効な署名IDから `Developer ID Application: ...` を選び、ダブルクォート内の名前全体を -`APPLE_SIGNING_IDENTITY` に指定する。以下の `YOUR NAME (TEAMID)` は実際の表示に置き換える。 -環境変数を設定するだけでは証明書は作成されない。 +表示された `Developer ID Application: ...` の名前全体を指定する。 +公証プロファイルは `xcrun notarytool store-credentials` で事前登録した名前を使う。 +Apple ID認証ではアプリ用パスワードが必要。認証情報はJSONへ保存しない。 ```sh export APPLE_SIGNING_IDENTITY='Developer ID Application: YOUR NAME (TEAMID)' export APPLE_NOTARY_PROFILE='your-notary-profile' ``` -配布用は `macos.sign` / `macos.notarize` を両方 `true` にする。 -またはSTEP5のmacOSコマンドに `NEXT2D_STEAM_RELEASE=1` を付けると、JSONのfalse指定に関わらず両方を必須にできる。 -認証情報不足・署名失敗・公証失敗はビルド失敗となる。 -署名エラーは公証へ進まずに停止する。`Signature=adhoc` / `TeamIdentifier=not set` が出る場合は、 -Developer ID署名が付いていないため、先に表示された署名エラーとキーチェーンの証明書・秘密鍵を確認する。 - -Steam用のターゲットは `darwin`。Valveは新規macOSアプリに64bitとAppleの公証を要求する。 -テンプレートのentitlementsはJITとSteam Overlay用のlibrary validation / DYLD設定を含み、 -`com.apple.security.app-sandbox` は付けない（Chromiumのrenderer sandboxとは別）。 -[Valveのプラットフォーム要件](https://partner.steamgames.com/doc/store/application/platforms) / -[Electron Packagerの署名・公証設定](https://electron.github.io/packager/main/interfaces/Options.html) +署名・公証が失敗したらアップロードへ進まない。`Signature=adhoc` / `TeamIdentifier=not set` はDeveloper ID署名未完了。 -#### SteamCMDとビルドアカウント +#### SteamCMD -[Steamworks SDKのContentBuilder](https://partner.steamgames.com/doc/sdk/uploading)にある実行OS用のSteamCMDを用意する。 -Windowsは `steamcmd.exe`、macOS / Linuxは `steamcmd.sh` を使用できる。 -PATH上の `steamcmd`（Windowsは `steamcmd.exe`）を使うか、環境変数 `STEAMCMD` に実行ファイルのパスを指定する。 -引数やシェルコマンドを含めず、パスだけを指定する。`.sh` は実行権限が必要。 -SteamCMD自体の実行に必要なOSライブラリはSteamCMDの手順に従って用意する。 - -アップロード用アカウントには対象アプリの `Edit App Metadata` と `Publish App Changes To Steam` の権限を付与する。 -macOS / Linuxの設定例（配置先とアカウント名を置き換える）: +[Steamworks SDKのContentBuilder](https://partner.steamgames.com/doc/sdk/uploading)からSteamCMDを用意する。 +ビルドアカウントには `Edit App Metadata` と `Publish App Changes To Steam` を付与する。 +macOS / Linuxの例（パスとSteamログイン名を置き換える）: ```sh export STEAMCMD="/absolute/path/to/steamcmd.sh" @@ -153,21 +108,14 @@ export STEAM_USERNAME="your_build_account" "$STEAMCMD" +login "$STEAM_USERNAME" +quit ``` -初回ログインではSteamCMDにパスワードと、要求された場合はSteam Guardコードを対話入力する。 -ログイン成功後も、`+quit` による正常終了まで待ち、通常のターミナルのプロンプトに戻ったことを確認する。 -`Steam>` で手動ログインした場合も、`quit` を入力して終了してからアップロードへ進む。 -その後builderは同じSteamCMD・同じアカウントの保存済みログインを使い、パスワードをコマンド引数へ渡さない。 -Steamアプリへのログインだけでは、このSteamCMDの認証準備を完了したことにはならない。 - -アップロード時に `Cached credentials not found` / `No cached credentials and @NoPromptForPassword is set` が出た場合や、 -認証が失効した場合は、上の `"$STEAMCMD" +login "$STEAM_USERNAME" +quit` を再実行し、正常終了後にアップロードを再実行する。 -builderからの実行は対話入力を待たず失敗させるため、builderの再実行だけではログイン情報を登録できない。 -CIではSteamCMDの `config/config.vdf` をSecretとして復元・管理し、ビルド成果物に含めない。 -Windows PowerShellでは `$env:STEAMCMD` と `$env:STEAM_USERNAME` を設定する。 +- パスワード・要求されたSteam Guardコードを入力し、**ログイン後の正常終了まで待つ**。手動ログインなら `quit` で終了する。 +- builderは同じSteamCMD・アカウントの保存済み認証を使う。`Cached credentials not found` が出たら上のログインコマンドを再実行する。 +- Windowsは `steamcmd.exe` とPowerShellの `$env:STEAMCMD` / `$env:STEAM_USERNAME` を使用。`STEAMCMD` は実行ファイルのパスのみ、`.sh` は実行権限が必要。 +- CIではSteamCMDの `config/config.vdf` をSecretとして復元し、成果物に含めない。 -### STEP5：各OSを書き出し、成果物を揃える +### STEP5：書き出し・成果物を確認する -ゲームルートで必要なOSのコマンドを実行する。書き出しはアップロード・公開を行わない。 +ゲームルートで実行する。追加のアプリビルドやインストーラー作成は不要。 ```sh npx @next2d/builder --platform steam:windows --env prd @@ -175,31 +123,12 @@ npx @next2d/builder --platform steam:macos --env prd npx @next2d/builder --platform steam:linux --env prd ``` -CPUを変える場合は `--arch arm64` などを追加する。 -テンプレートの `npm run build:steam:windows` / `build:steam:macos` / `build:steam:linux` も同じ処理を行い、 -`--env prd` を指定済み。npm経由の引数は `-- --arch arm64` や `-- --env dev` で渡す。 - -既定の出力先は `dist/steam//build//`。 - -| OS | 配布するフォルダ全体 | OS別DepotのExecutable | 共有DepotのExecutable | -|---|---|---|---| -| Windows | `My Game-win32-x64/` | `my-game.exe` | `windows/my-game.exe` | -| macOS | `My Game-darwin-universal/` | `My Game.app` | `macos/My Game.app` | -| Linux | `My Game-linux-x64/` | `my-game` | `linux/my-game` | - -実際の起動パス・CPU・ContentRootは `*-steampipe/launch.json` を参照する。 -実行ファイルだけでなく、Electronのライブラリ・locales・ライセンス・resourcesを含むフォルダ全体が配布対象。 -Steam用のDMG/DEB/MSIは不要で、書き出し後に追加のアプリビルドは行わない。 - -別マシンやCIの成果物は、`steam-package.json` と `*-steampipe/` を含む各OSの `build//` を -同じ `dist/steam//build//` 構成に集める。macOSのシンボリックリンクとLinuxの実行権限を保つため、 -CI artifactは `tar.gz` にして転送する。カスタム出力先はSTEP6の `--steam-root` で指定する。 - -設定・バージョンを変えたら対象OSを再書き出しする。同じバージョン番号でも全OSを意図したリビジョンで揃える。 -同じOSのx64とarm64を順に書き出すと、最後に成功したCPUの成果物を使う。 -同じOSの複数CPUを1つの共有Depotへ同時に統合する処理は行わない。 +- CPU変更は `--arch arm64` 等を追加する。同一OSは最後に成功したCPUの成果物を使う。 +- 出力は `dist/steam//build//`。実行ファイルだけでなく、配下のフォルダ全体を保持する。 +- 別マシン・CIから集める場合も `steam-package.json` と `*-steampipe/` を含む同じ階層を保つ。`tar.gz` で転送し、シンボリックリンク・実行権限を維持する。 +- 設定・バージョン変更後は対象OSを再書き出しする。アップロード対象の全OSを同じバージョン・意図したリビジョンで揃える。 -配布用macOSアプリは署名・公証・staple完了を確認する（パスは成果物に合わせる）: +macOS配布用は次を実行する（パスは成果物に合わせる）: ```sh codesign --verify --deep --strict --verbose=2 'dist/steam/macos/build/prd/My Game-darwin-universal/My Game.app' @@ -209,219 +138,97 @@ echo $? ``` | 検証 | 正常時の出力 | 直後の `echo $?` | -| --- | --- | --- | -| `codesign --verify --deep --strict --verbose=2` | アプリのパスに続いて `valid on disk` と `satisfies its Designated Requirement` が表示される。内部コードの検証結果が追加で表示される場合もある。 | `0` | -| `xcrun stapler validate` | 最後に `The validate action worked!` が表示される。 | `0` | +|---|---|---| +| `codesign` | `valid on disk` / `satisfies its Designated Requirement` | `0` | +| `stapler` | `The validate action worked!` | `0` | -`codesign` は `--verbose=2` を付けない場合、成功しても通常は何も表示しない。終了コードが `0` なら検証成功と判断できる。 -`echo $?` は確認したいコマンドの直後に実行する。`0` 以外なら検証失敗なので、出力されたエラーを解消して再確認する。 -これらは署名と添付済み公証チケットを検証するコマンドであり、署名・公証を実施する操作ではない。 -両方が成功した後も、STEP6でSteamからのインストール・起動を確認する。 +`0` 以外ならエラーを解消して再検証する。これらは検証コマンドで、署名・公証自体は実行しない。 -参考：[Appleの署名検証手順](https://developer.apple.com/library/archive/documentation/Security/Conceptual/CodeSigningGuide/Procedures/Procedures.html)。 +### STEP6：起動設定・アップロード・動作確認 -### STEP6：起動設定を反映し、アップロード・テストする +#### 起動ファイルを設定する -SteamworksのInstallation > General InstallationにOS別Launch Optionを追加する。 -ExecutableはSTEP5の `launch.json` に合わせ、Arguments/Working Directoryは空欄にする。 -x64版は64bit条件を指定する。対応OS・最低OS要件は同梱Electronと実機検証に合わせ、Steamworksで変更をPublishする。 +SteamworksのInstallation > General InstallationでOS別Launch Optionを設定する。 +**同じDepot IDを複数OSで使う場合に、起動パスへOS名が付く。** 例はSTEP3のゲーム名・実行ファイル名に対応する。 -ゲームルートで次を実行する。共有Depot・OS別Depotをまとめて1回のAppBuildでアップロードする。 -Web/Electronの再ビルドや事前の `--steam-manifest` 実行は不要。 +| Depot構成 | WindowsのExecutable | macOSのExecutable | LinuxのExecutable | +|---|---|---|---| +| 単一Depot・単一OS（Windowsの例） | `my-game.exe` | — | — | +| 単一Depot・全OS共用 | `windows/my-game.exe` | `macos/My Game.app` | `linux/my-game` | +| 複数Depot・OS別 | `my-game.exe` | `My Game.app` | `my-game` | +| 複数Depot・Windows/macOSのみ共用 | `windows/my-game.exe` | `macos/My Game.app` | `my-game` | -```sh -# ローカル検証のみ。SteamCMD・認証・Steamへの接続は不要 -npx @next2d/builder --steam-upload --env prd --dry-run +- 単一OSがmacOS / Linuxの場合もOS名を付けず、`My Game.app` / `my-game` を指定する。 +- インストール先からの相対パスを使い、`dist/steam/...` は含めない。実際の値は `*-steampipe/launch.json` またはdry-runで確認する。 +- Arguments / Working Directoryは空欄。OS・CPU条件（x64は64bit）を設定し、公開（Publish）で反映する。Depot構成変更時は起動パスも更新する。 -# STEP4のSteamCMDログイン・正常終了後、同じターミナルで設定したブランチへアップロード -npx @next2d/builder --steam-upload --env prd -``` +#### アップロードする -任意のアップロードコメントを付ける場合は `--steam-comment` を指定する。 -Steamworksの「あなたのビルド」の説明（SteamPipeの `Desc`）に反映される。 +STEP4のログインが正常終了したターミナルで実行する。 ```sh -npx @next2d/builder --steam-upload --env prd --steam-comment "内部テスト：ゲームパッド操作を修正" +npx @next2d/builder --steam-upload --env prd --dry-run +npx @next2d/builder --steam-upload --env prd ``` -| 引数・設定 | 用途 | -|---|---| -| `--steam-branch internal` | `steam.branch` の反映先を上書き。`SetLive` で反映を要求する。`default` は指定不可で、一般公開用ビルドの切り替えはSteamworksで行う。 | -| `--steam-comment "コメント"` | アップロードコメントを指定する。未指定時は従来どおり ` (, )`。空白のみ・改行・制御文字・ダブルクォート・バックスラッシュは使用不可。`--dry-run` の出力と `upload-plan.json` でも確認できる。 | -| `--steam-root dist/steam` | 成果物の収集先。既定は `dist/steam`。ゲームルートからの相対パスまたは絶対パス。アップロード時はVite設定を読まないため、カスタム出力先では明示する。 | -| `--dry-run` | パッケージと設定の整合性を検証する。Steam側の権限・ブランチ・パスワードの確認は行わない。 | -| 併用しない引数 | `--build` / `--preview` / `--open` / `--steam-manifest` / `--arch`。`--platform` も不要。 | - -対応するテンプレートのnpmスクリプトは `upload:steam:check` / `upload:steam`。 - -builderは `steam.depots` に設定された全OSの `steam-package.json` と実行ファイルを検証し、 -App ID・Depot ID・バージョン・ゲーム名・CPUに不足や不整合があればSteamCMD起動前に停止する。 -VDFは検証結果から再生成する。通常の書き出し用VDFは変更しない。 - -| 保存先（`--steam-root` 配下） | 内容 | -|---|---| -| `uploads//-<識別子>/` | VDF、`upload-plan.json`。dry-runは `Preview=1`、`SetLive`なし。アップロード成功時はBuildIDを `upload-result.json` に記録。 | -| `uploads//cache//` | SteamPipeのログ・差分キャッシュ。 | - -SteamworksのBuilds画面で、記録されたBuildIDが対象ブランチの現在のビルドになっていることを確認する。 -アカウントやアプリの状態によってSteam側の追加確認が必要になる場合がある。 -テスターはSteamクライアントのプロパティ > ゲームバージョンとベータでパスワードを入力し、`internal` を選ぶ。 -各OSでインストール・起動を確認し、macOS UniversalはIntel / Apple Siliconの両方でテストする。 - -### 参照：VDFの生成と手動アップロード +設定した全OSの成果物を検証し、全Depotを1回でアップロードする。事前の `--steam-manifest` は不要。 +dry-runはローカル検証のみで、Steam側の権限・ブランチ・パスワードは確認しない。 -builderのSTEP6を使う場合、この節の操作は不要。SteamCMDを直接操作する場合に使う。 - -| 構成 | 通常の書き出し時のVDF生成先・条件 | +| 任意の引数 | 用途 | |---|---| -| OS別Depot | 各OSの `*-steampipe/`。 | -| 共有Depot | 全対象OSが揃うと `dist/steam/shared//depot-/`。不足OSは `launch.json` に記録し、アップロード用VDF・OS単独VDFは生成しない。 | - -一部OSだけDepot IDを共有する構成にも対応する。`FileMapping` でOS別サブディレクトリへ配置し、アセットは再コピーしない。 -別マシンの成果物を集めた後に共有DepotのVDFだけを再生成する場合: +| `--steam-branch internal` | 反映先を上書き。`default` への切り替えはSteamworksで行う。 | +| `--steam-comment "操作修正"` | ビルド説明。未指定は ` (, )`。空白のみ・制御文字・改行・ダブルクォート・バックスラッシュは不可。 | +| `--steam-root dist/steam` | 成果物の収集先。カスタム出力先では指定必須。 | -```sh -npx @next2d/builder --platform steam:macos --env prd --steam-manifest -``` +アップロードには `--platform` / `--arch` / `--build` / `--preview` / `--open` / `--steam-manifest` を併用しない。 -npmの別名は `build:steam:manifest`（別環境なら `-- --env dev`）。このコマンドはどのOSでも実行でき、 -`--platform` はVite設定を読むための指定で、設定内のすべての共有Depotを統合する。 -`build.outDir` と `--env` から最新の成功した書き出しを選び、App ID・Depot ID・ゲーム名・実行ファイル名・バージョンを検証する。 -不足パッケージは終了コード1となり、古い統合VDFは再生成時に無効化する。 -`--arch` / `--preview` / `--build` / `--open` とは併用できない。 +#### 完了を確認する -`app_preview.vdf` はファイルマッピング検証、`app_build.vdf` はアップロード、 -`depot_build.vdf` はフォルダ内容の再帰マッピング用。`steam_appid.txt` は配布対象から除外する。 -ContentRootはVDFからの相対パスなので、単独Depotはアプリと `*-steampipe/` をセットで、共有Depotは `dist/steam/` 全体の構成を保って移動する。 +1. `dist/steam/uploads//-<識別子>/upload-result.json` のBuildIDが、Steamworksの対象ブランチに反映されていることを確認する。カスタム出力先では `dist/steam` を読み替える。 +2. Steamクライアントのプロパティ > ゲームバージョンとベータでパスワードを入力し、`internal` を選ぶ。 +3. 各OSでインストール・起動・終了・入力・音声・全画面・オフライン起動・更新後の保存を確認する。macOS UniversalはIntel / Apple Silicon両方で確認する。 +4. 対応を掲げるOverlay・Steam Deck・Linux環境を実機で確認し、ストア記載と一致させる。実績・DRM・Steam Cloudは自動統合されない。 -```text -steamcmd +login BUILD_ACCOUNT +run_app_build "/absolute/path/to/app_preview.vdf" +quit -steamcmd +login BUILD_ACCOUNT +run_app_build "/absolute/path/to/app_build.vdf" +quit -``` - -通常の書き出し・`--steam-manifest` のVDFには `SetLive` がないため、アップロード後にSteamworksで対象ブランチへ設定する。 -OS別VDFは1つのDepotを更新するので、最終BuildのDepot manifestが全OSで意図した版になっているか確認する。 -[SteamPipe公式手順・VDF仕様](https://partner.steamgames.com/doc/sdk/uploading) - -### 参照：テンプレート・ホスト・移行 - -`create-next2d-app` はプロジェクト名から `appId`、`appName`、`executableName`、 -`companyName` を設定する。例えば `my-game` なら `appId` は `app.example.my-game`、 -他の3項目は `my-game` になる。配布前にbundle IDと会社名を自分の値へ変更する。 -CPU設定が省略されている場合はOSごとの既定値を補い、テンプレートに指定済みの値は保持する。 -アイコンパスやSteam IDなどの設定も保持する。 - -Electron用コードはbuilderが管理する。OSの一時ディレクトリにホスト・runtime設定・Web資産を配置し、失敗時を含め書き出し後に削除する。 -ゲーム側へ `electron/`、Electron用 `node_modules` / lockfileは作らない。 -Electronは `templates/electron/package.json`、Packagerは `src/tool-packages.ts` の固定バージョンを取得・キャッシュする。 -PackagerはElectron書き出し時のみ取得し、OS別パッケージ・アイコン・署名・公証を処理する。 -ホストにはnpm依存やネイティブアドオンがないため、ABIに合わせた再ビルドは不要。 -プレビューは実行ホストのOS/CPUで書き出した `dist//build//` のアプリを起動する。 - -旧 `electron/` のホストコード・`config.forge`・独自npm依存は参照しない。 -移行時はアイコンを共通アセットへ移し、JSONのパスを更新してから旧ディレクトリを削除する。 -独自main/preloadやネイティブアドオンがある場合は、先にbuilder側への対応が必要。 - -テンプレートのホストは絶対パスと固定origin `next2d://game` で資産を読む。 -起動時の作業ディレクトリに依存せず、ローカルfetch・Worker・localStorageが使える。 -F11/Alt+Enterで全画面、Escapeで解除。閉じるとmacOSでもプロセスを終了する。 -Node integration無効・context isolation/sandbox有効、外部ページ遷移と新規ウィンドウは禁止。 -Next2D用CSPを付与する。外部APIを使うゲームでは接続先を明示的に追加すること。 -[Electron security](https://www.electronjs.org/docs/latest/tutorial/security) / -[protocol](https://www.electronjs.org/docs/latest/api/protocol) - -保存先はElectronのappData配下の `appId` ディレクトリ。 -表示名を変えても保存先は変わらない。旧file-originの開発版セーブは自動移行しない。 -Steam Cloudは未統合。Chromiumプロファイル全体をCloud対象にせず、導入時は -ゲーム用のセーブファイルとアカウント単位の保存方式を別途設計する。 -[Steam Cloud](https://partner.steamgames.com/doc/features/cloud) - -### リリース前の確認範囲 - -STEP6のインストール・起動確認に加えて、以下を検証する。 - -- 終了動作、オフライン起動、更新後の保存データ。 -- マウス/キーボード/コントローラ、解像度・全画面切替、音声、スリープ復帰。 -- Shift+Tab Overlay。Electronは複数プロセスなので、OS/GPUごとに実動作を確認する。 - この書き出しはSteamworks SDK・実績・DRM・Overlay APIを統合しない。 - SDK統合はSteam配布の必須条件ではない。 -- LinuxはSteam Linux Runtime環境で依存ライブラリとsandboxを確認する。 - `--no-sandbox` を配布用の回避策にしない。 -- Steam DeckのVerified判定は別審査。Linux版が生成できたことだけでは対応完了にならない。 - コントローラだけで操作できること、文字の可読性、画面表示等を実機で確認する。 -- Steamのビルド審査前に、ストアで宣言したOS・機能と動作が一致することを確認する。 - -[Steamworks API](https://partner.steamgames.com/doc/sdk/api) / -[Overlay](https://partner.steamgames.com/doc/features/overlay) / -[Linux開発](https://partner.steamgames.com/doc/store/application/platforms/linux) / -[Steam Deck互換性](https://partner.steamgames.com/doc/steamhardware/compat) / -[ビルド審査](https://partner.steamgames.com/doc/store/review_process) +エラー時のSteamPipeログは `dist/steam/uploads//cache//` を確認する。 ## English -Local exports do not require Steamworks, SteamCMD or distribution signing credentials. - -### STEP1: Prepare target environments and icons +For local exports, follow STEP1, STEP3 and STEP5. Steam distribution requires all steps. -- Build macOS Universal applications and perform macOS signing/notarization on macOS. -- Place Windows ICO, macOS ICNS and Linux PNG icons in `src/assets/icons/` in the Next2D Framework template. - Replace template placeholders before distribution. STEP3 documents omitted icon settings. +### STEP1: Prepare the environment and icons -#### Supported operating systems and architectures +Run macOS Universal exports, signing and notarization on macOS. +Replace the template icons in `src/assets/icons/` with Windows ICO, macOS ICNS and Linux PNG files. -| OS | Default | Accepted `architectures` / `--arch` values | +| OS | Default CPU | Accepted `architectures` / `--arch` values | |---|---|---| | Windows | `x64` | `x64`, `arm64` | | macOS | `universal` | `x64`, `arm64`, `universal` | | Linux | `x64` | `x64`, `arm64` | -### STEP2: Prepare the Steamworks app, depots and testing branch (Steam distribution) +### STEP2: Configure Steamworks -1. Find the issued App ID in the app's Steamworks administration page. -2. Create depots in SteamPipe > Depots and select their operating systems. Use All languages for shared language content, - save with Save Changes, then apply the changes on the Publish tab. - Include the required depots in development, testing and retail Packages. **Use actual Depot IDs; do not infer them from the App ID.** -3. Create an `internal` branch in SteamPipe > Builds and **set a password shared only with the intended testers.** - The name alone does not make it private. The builder does not create branches, configure passwords or verify protection. -4. Give testers access to the game and its depots. For external testers of an unreleased game, use Release State Override - (beta) keys or another appropriate method. A branch password alone does not grant game access. - Keep the password out of JSON and the repository, and ask testers not to share it with others. +1. Find the issued App ID. +2. Create depots in SteamPipe > Depots and set their OS/language. Save, then apply the changes on the Publish tab. +3. Include the required depots in the relevant development, testing and retail Packages. +4. Create an `internal` branch in SteamPipe > Builds and set a password. +5. Give testers game/depot access and the branch password. Use Release State Override keys or equivalent access for external testing before release. -#### Multiple depots and builder support +**A branch password does not grant game access.** The builder does not create branches or configure passwords. -**Steam supports multiple depots under one App ID.** Valve recommends separate depots for OS-specific files. - -| Configuration | Steam | Current builder | -|---|---|---| -| Separate depots for Windows / macOS / Linux | Supported. Set the target OS for each depot. | Supported. Assign different issued IDs to the OS entries in `steam.depots`. | -| One depot containing multiple operating systems | Supported. Set its OS selection accordingly, such as All OSes. | Supported. Assign the same ID to those operating systems. Files are placed in OS subdirectories. Distributing every included OS's files increases download size. | -| Only some operating systems share a depot | Supported. | Supported. Assign the same ID only to those operating systems. | -| Multiple depots for one OS, such as the application, common assets and languages | Supported. Their contents are combined during installation. | Not supported. Each OS accepts a single Depot ID; arrays and extra asset keys are not supported. | - -The builder accepts one ID per OS, for a maximum of three distinct IDs overall. This is a limit of the builder's configuration format, not a Steam limit. -See STEP5 for collecting OS packages and launch paths, and STEP6 for uploading multiple depots in one operation. - -Steam selects downloads based on Package ownership and depot conditions such as OS and language. -If simultaneously installed depots contain the same path, the depot later in the list takes priority, so check file placement. -Configure these selection conditions in Steamworks; the builder's JSON does not apply them. +| Depot layout | Configuration | +|---|---| +| Separate per OS (Valve recommendation) | Assign a different issued Depot ID to each OS. | +| Shared across operating systems | Assign the same ID and set the Steamworks OS selection accordingly, such as All OSes. All included OS files are distributed. | -`internal` / `beta` are branches that select an app build; separate depots are not required for each branch. -In this document, a "shared depot" groups multiple operating systems within the same app. -Steamworks' "Add Shared Depot" references a depot from another app; it is a separate operation from assigning the same ID in the builder. +Steam supports multiple depots. The builder accepts one ID per OS, including layouts where only some operating systems share a depot. +Splitting one OS across multiple depots is not supported. Separate depots per branch are unnecessary. -[Depot configuration](https://partner.steamgames.com/doc/store/application/depots) / -[Packages and access](https://partner.steamgames.com/doc/store/application/packages) / -[Uploading multiple depots](https://partner.steamgames.com/doc/sdk/uploading) / -[Beta branches](https://partner.steamgames.com/doc/store/application/branches) / -[Testing on Steam](https://partner.steamgames.com/doc/store/testing) / -[Release State Override keys](https://partner.steamgames.com/doc/features/keys) +Official: [Depots](https://partner.steamgames.com/doc/store/application/depots) / [Packages](https://partner.steamgames.com/doc/store/application/packages) / [Testing and access](https://partner.steamgames.com/doc/store/testing) ### STEP3: Configure electron.config.json -Manage game-specific settings in `electron.config.json` at the project root. -Both JavaScript and TypeScript templates include it; replace the defaults with your game's values. -`appId` is the macOS bundle ID and the identifier used for the save location; `steam.appId` is Valve's numeric App ID. -These are separate identifiers. The game version comes from the root `package.json`. +Edit the configuration at the game root. The version comes from the root `package.json`. ```json { @@ -445,62 +252,44 @@ These are separate identifiers. The game version comes from the root `package.js } ``` -| Field | Purpose / behavior | Defaults / notes | -|---|---|---| -| `companyName` | Company name in the Windows executable metadata. | Falls back to `author.name` in `package.json`, then to the game name. | -| `appName` / `executableName` | `appName` is the window and application name. `executableName` is the executable file name. | The display name and executable name can be set independently. | -| `description` | Optional description used in the generated Electron host's `package.json` and the Windows file description. | The JSON value takes priority. If omitted or `null`, uses `description` from the root `package.json`. If both are absent, uses an empty string. An explicit `""` also remains empty. | -| `icons` | Icon paths, relative to the project root or absolute. Use ICO for Windows, ICNS for macOS and PNG for Linux. | Each key is optional. Omitted platforms use the builder's placeholder Next2D icons; `"icons": {}` uses placeholders for every OS. A specified file that does not exist causes an error. | -| `architectures` | CPU architecture per OS. See STEP1 for supported operating systems and architectures. | Defaults to `x64` for Windows/Linux and `universal` for macOS. `--arch` takes priority. | -| `steam.appId` | Valve's numeric App ID. Set to `null` if it has not been issued. | Local exports still work without an App ID, but SteamPipe VDFs are not generated. | -| `steam.branch` | Target beta branch for `--steam-upload`. | Defaults to `internal`. `--steam-branch` takes priority. Create the branch and configure its password in Steamworks. | -| `steam.depots` | Actual Depot IDs created in Steamworks. Assigning the same ID to multiple operating systems combines them in one depot. | Do not infer Depot IDs from the App ID. If `null` or omitted, only the application and launch metadata are generated, without upload VDFs. | -| `macos` | macOS signing and notarization settings. | Use `false` for both `sign` / `notarize` during local testing. Enable both for production distribution. | - -### STEP4: Prepare signing and upload credentials (distribution) +| Field | Setup / checks | +|---|---| +| `appId` | Bundle ID and save location identifier, separate from the Steam App ID. Replace before distribution. | +| `appName` / `executableName` | Application display name / executable file name. | +| `companyName` | Windows company name. Falls back to `author.name` in `package.json`, then the game name. | +| `description` | Optional. Omitted or `null` uses the description from `package.json`. | +| `icons` | Paths relative to the game root, or absolute paths. Omitted OS entries use placeholders; missing specified files cause an error. | +| `architectures` | CPU settings from STEP1. `--arch` takes priority. | +| `steam.appId` / `steam.depots` | For distribution, replace `null` with actual App/Depot IDs. Do not infer Depot IDs from the App ID. Operating systems without a Depot ID are excluded from uploading. | +| `steam.branch` | Target branch; defaults to `internal`. | +| `macos.sign` / `macos.notarize` | Both `false` for local testing; both `true` for distribution. | + +### STEP4: Prepare credentials #### macOS signing and notarization -Install a Developer ID Application certificate and its matching private key in the macOS keychain, and save a notarization profile using -`xcrun notarytool store-credentials`. Do not put credentials in JSON. - -Use the following command to find the signing identity to set as `APPLE_SIGNING_IDENTITY`: +Install a **Developer ID Application certificate and private key** in the keychain, then find the signing identity: ```sh security find-identity -v -p codesigning ``` -Choose a valid `Developer ID Application: ...` identity from the output and use the entire name inside the double quotes -for `APPLE_SIGNING_IDENTITY`. Replace `YOUR NAME (TEAMID)` below with the actual value shown. -Setting the environment variable does not create a certificate. +Use the complete `Developer ID Application: ...` name shown. +Use a notarization profile previously registered with `xcrun notarytool store-credentials`. +Apple ID authentication requires an app-specific password. Do not store credentials in JSON. ```sh export APPLE_SIGNING_IDENTITY='Developer ID Application: YOUR NAME (TEAMID)' export APPLE_NOTARY_PROFILE='your-notary-profile' ``` -For distribution, set both `macos.sign` / `macos.notarize` to `true`. -Alternatively, prefix the STEP5 macOS command with `NEXT2D_STEAM_RELEASE=1` to require both even when JSON specifies false. -Missing credentials, signing failures or notarization failures fail the build. -Signing failures stop before notarization. If the output shows `Signature=adhoc` / `TeamIdentifier=not set`, -the app lacks a Developer ID signature; check the preceding signing error and the certificate/private key in the keychain. - -Steam uses the `darwin` target. Valve requires 64-bit support and Apple notarization for new macOS applications. -The template entitlements include library validation / DYLD settings for JIT and Steam Overlay, -without `com.apple.security.app-sandbox` (which is separate from Chromium's renderer sandbox). -[Valve platform requirements](https://partner.steamgames.com/doc/store/application/platforms) / -[Electron Packager signing and notarization options](https://electron.github.io/packager/main/interfaces/Options.html) - -#### SteamCMD and the build account +Resolve signing/notarization failures before uploading. `Signature=adhoc` / `TeamIdentifier=not set` means Developer ID signing is incomplete. -Obtain SteamCMD for your host OS from the [Steamworks SDK ContentBuilder](https://partner.steamgames.com/doc/sdk/uploading). -Use `steamcmd.exe` on Windows or `steamcmd.sh` on macOS / Linux. -The builder uses `steamcmd` on PATH (`steamcmd.exe` on Windows), or the executable path set in `STEAMCMD`. -Specify only the path, without arguments or a shell command. A `.sh` file needs executable permission. -Install any OS libraries required by SteamCMD according to its setup instructions. +#### SteamCMD -Grant the upload account `Edit App Metadata` and `Publish App Changes To Steam` permissions for the target app. -Example for macOS / Linux; replace the path and account name: +Obtain SteamCMD from the [Steamworks SDK ContentBuilder](https://partner.steamgames.com/doc/sdk/uploading). +Grant the build account `Edit App Metadata` and `Publish App Changes To Steam` permissions. +Example for macOS / Linux; replace the path and Steam login name: ```sh export STEAMCMD="/absolute/path/to/steamcmd.sh" @@ -508,21 +297,14 @@ export STEAM_USERNAME="your_build_account" "$STEAMCMD" +login "$STEAM_USERNAME" +quit ``` -During the first login, enter the password and, if requested, the Steam Guard code interactively in SteamCMD. -After login succeeds, wait for `+quit` to exit normally and confirm that the regular terminal prompt has returned. -If you log in manually at the `Steam>` prompt, also enter `quit` before proceeding to upload. -The builder then reuses the saved login for the same SteamCMD installation and account without passing a password as a command-line argument. -Logging into the Steam desktop app alone does not confirm that this SteamCMD authentication setup is complete. +- Enter the password and any requested Steam Guard code, then **wait for normal exit after login**. After manual login, enter `quit`. +- The builder reuses saved credentials for the same SteamCMD/account. If `Cached credentials not found` appears, rerun the login command above. +- On Windows, use `steamcmd.exe` and PowerShell's `$env:STEAMCMD` / `$env:STEAM_USERNAME`. `STEAMCMD` accepts only an executable path; `.sh` files need executable permission. +- In CI, restore SteamCMD's `config/config.vdf` from a Secret and exclude it from artifacts. -If uploading reports `Cached credentials not found` / `No cached credentials and @NoPromptForPassword is set`, or authentication expires, -rerun `"$STEAMCMD" +login "$STEAM_USERNAME" +quit` above, wait for it to exit normally, then retry the upload. -Builder uploads fail instead of waiting for interactive input, so retrying the builder alone cannot register login credentials. -In CI, restore and manage SteamCMD's `config/config.vdf` as a Secret and exclude it from build artifacts. -In Windows PowerShell, set `$env:STEAMCMD` and `$env:STEAM_USERNAME`. +### STEP5: Export and check the packages -### STEP5: Export each OS and collect the packages - -Run the required OS commands from the game root. Exporting does not upload or publish anything. +Run from the game root. No additional application build or installer is needed. ```sh npx @next2d/builder --platform steam:windows --env prd @@ -530,31 +312,12 @@ npx @next2d/builder --platform steam:macos --env prd npx @next2d/builder --platform steam:linux --env prd ``` -Append an option such as `--arch arm64` to change the architecture. -Template scripts `npm run build:steam:windows` / `build:steam:macos` / `build:steam:linux` perform the same operations -and already specify `--env prd`. Pass npm arguments with `-- --arch arm64` or `-- --env dev`. - -The default output location is `dist/steam//build//`. - -| OS | Entire folder to distribute | Separate depot Executable | Shared depot Executable | -|---|---|---|---| -| Windows | `My Game-win32-x64/` | `my-game.exe` | `windows/my-game.exe` | -| macOS | `My Game-darwin-universal/` | `My Game.app` | `macos/My Game.app` | -| Linux | `My Game-linux-x64/` | `my-game` | `linux/my-game` | - -Read the actual launch path, architecture and ContentRoot from `*-steampipe/launch.json`. -Distribute the entire folder, including Electron libraries, locales, licenses and resources. -Steam needs no DMG/DEB/MSI installer, and no additional application build is required after export. +- Append `--arch arm64` or another supported value to change the CPU. Each OS uses its last successful architecture export. +- Output is under `dist/steam//build//`. Keep the entire contents, not just the executable. +- When collecting packages from other machines or CI, preserve this layout, including `steam-package.json` and `*-steampipe/`. Transfer as `tar.gz` to retain symlinks and executable permissions. +- Re-export affected operating systems after configuration/version changes. Keep every upload target on the same version and intended revision. -For separate machines or CI, collect each OS's `build//`, including `steam-package.json` and `*-steampipe/`, -under the same `dist/steam//build//` layout. Transfer CI artifacts as `tar.gz` to preserve macOS symlinks -and Linux executable permissions. Use STEP6's `--steam-root` for a custom output location. - -Re-export affected operating systems after changing configuration or version. Even with an unchanged version number, -keep all OS packages on the intended revision. When exporting x64 and arm64 successively for one OS, the last successful -architecture is used. Combining multiple architectures of one OS into a shared depot is not supported. - -Verify signing, notarization and stapling for macOS distribution packages (adjust the paths): +For macOS distribution, run these checks with your package path: ```sh codesign --verify --deep --strict --verbose=2 'dist/steam/macos/build/prd/My Game-darwin-universal/My Game.app' @@ -564,151 +327,55 @@ echo $? ``` | Check | Successful output | Immediately following `echo $?` | -| --- | --- | --- | -| `codesign --verify --deep --strict --verbose=2` | The app path followed by `valid on disk` and `satisfies its Designated Requirement`. Additional results for nested code may also appear. | `0` | -| `xcrun stapler validate` | Ends with `The validate action worked!`. | `0` | - -Without `--verbose=2`, `codesign` normally prints nothing on success. An exit code of `0` indicates that verification passed. -Run `echo $?` immediately after each command you want to check. A nonzero exit code means verification failed; resolve the reported error and check again. -These commands verify the signature and the attached notarization ticket; they do not sign or notarize the app. -After both checks pass, still verify installation and launching through Steam in STEP6. +|---|---|---| +| `codesign` | `valid on disk` / `satisfies its Designated Requirement` | `0` | +| `stapler` | `The validate action worked!` | `0` | -Reference: [Apple's signature verification instructions](https://developer.apple.com/library/archive/documentation/Security/Conceptual/CodeSigningGuide/Procedures/Procedures.html). +Resolve nonzero results and verify again. These commands check the package; they do not sign or notarize it. ### STEP6: Configure launching, upload and test -Add OS-specific Launch Options in Steamworks under Installation > General Installation. -Use the Executable from STEP5's `launch.json`, leaving Arguments/Working Directory empty. -Set the 64-bit condition for x64. Match supported OS versions and minimum requirements to the bundled Electron and hardware testing, -then Publish the Steamworks changes. +#### Configure executable paths -Run these commands from the game root. Shared and separate depots are uploaded together in a single AppBuild. -No Web/Electron rebuild or prior `--steam-manifest` command is needed. +Set OS-specific Launch Options in Steamworks under Installation > General Installation. +**An OS prefix is added when multiple operating systems use the same Depot ID.** Examples use STEP3's application/executable names. -```sh -# Local validation only: no SteamCMD, credentials or Steam connection required -npx @next2d/builder --steam-upload --env prd --dry-run +| Depot layout | Windows Executable | macOS Executable | Linux Executable | +|---|---|---|---| +| One depot, one OS (Windows example) | `my-game.exe` | — | — | +| One depot shared by all operating systems | `windows/my-game.exe` | `macos/My Game.app` | `linux/my-game` | +| Multiple depots, separate per OS | `my-game.exe` | `My Game.app` | `my-game` | +| Multiple depots, Windows/macOS sharing only | `windows/my-game.exe` | `macos/My Game.app` | `my-game` | -# After STEP4's SteamCMD login exits normally, upload to the configured branch in the same terminal -npx @next2d/builder --steam-upload --env prd -``` +- A macOS-only / Linux-only depot also omits the OS prefix: use `My Game.app` / `my-game`. +- Paths are relative to the installation directory; omit `dist/steam/...`. Check actual values in `*-steampipe/launch.json` or dry-run output. +- Leave Arguments / Working Directory empty. Set OS/CPU conditions (64-bit for x64), then Publish. Update launch paths when changing depot layouts. + +#### Upload -Use `--steam-comment` to set an optional upload comment. -It appears as the description under "Your Builds" in Steamworks (SteamPipe's `Desc`). +Use the terminal where STEP4's login exited successfully. ```sh -npx @next2d/builder --steam-upload --env prd --steam-comment "Internal test: fix gamepad controls" +npx @next2d/builder --steam-upload --env prd --dry-run +npx @next2d/builder --steam-upload --env prd ``` -| Option / setting | Purpose | -|---|---| -| `--steam-branch internal` | Overrides `steam.branch`; requests activation through `SetLive`. `default` is not allowed. Switch public release builds through Steamworks. | -| `--steam-comment "Comment"` | Sets the upload comment. If omitted, keeps the existing ` (, )` format. Whitespace-only text, newlines, control characters, double quotes and backslashes are not allowed. Also shown in `--dry-run` output and `upload-plan.json`. | -| `--steam-root dist/steam` | Collected package location; defaults to `dist/steam`. Accepts an absolute path or a path relative to the game root. Specify custom output locations because uploading does not read the Vite configuration. | -| `--dry-run` | Validates packages against configuration. Does not check Steam permissions, branches or passwords. | -| Incompatible options | `--build` / `--preview` / `--open` / `--steam-manifest` / `--arch`. `--platform` is also unnecessary. | - -The corresponding template npm scripts are `upload:steam:check` / `upload:steam`. - -The builder checks `steam-package.json` and executables for every OS configured in `steam.depots`. -Missing or inconsistent App IDs, Depot IDs, versions, game names or architectures stop the operation before SteamCMD starts. -VDFs are regenerated from validated packages; ordinary export VDFs remain unchanged. +The builder validates all configured OS packages and uploads all depots in one operation. No prior `--steam-manifest` is needed. +Dry-run checks local files only, not Steam permissions, branches or passwords. -| Location (under `--steam-root`) | Contents | +| Optional argument | Purpose | |---|---| -| `uploads//-/` | VDFs and `upload-plan.json`. Dry runs use `Preview=1` without `SetLive`. Successful uploads record the BuildID in `upload-result.json`. | -| `uploads//cache//` | SteamPipe logs and incremental upload cache. | +| `--steam-branch internal` | Overrides the target branch. Switch `default` through Steamworks. | +| `--steam-comment "Input fix"` | Build description. Defaults to ` (, )`. Whitespace-only text, control characters, newlines, double quotes and backslashes are not allowed. | +| `--steam-root dist/steam` | Package collection root. Required for custom output locations. | -On the Steamworks Builds page, verify that the recorded BuildID is the target branch's current build. -Steam may request additional confirmation depending on the account or app state. -Testers enter the password and select `internal` in the Steam client's Properties > Game Versions & Betas. -Verify installation and launch on each OS, including both Intel and Apple Silicon for macOS Universal. +Do not combine uploads with `--platform` / `--arch` / `--build` / `--preview` / `--open` / `--steam-manifest`. -### Reference: VDF generation and manual uploading +#### Verify completion -Skip these operations when using the builder in STEP6. This section is for direct SteamCMD use. - -| Layout | VDF output and conditions during ordinary export | -|---|---| -| Separate OS depots | Each OS's `*-steampipe/` directory. | -| Shared depots | `dist/steam/shared//depot-/` once all required OS packages exist. Missing operating systems are listed in `launch.json`; neither upload VDFs nor standalone per-OS VDFs are generated for an incomplete group. | - -Some operating systems may share a Depot ID while others use separate depots. `FileMapping` assigns OS subdirectories without copying assets again. -To regenerate only shared depot VDFs after collecting packages from separate machines: - -```sh -npx @next2d/builder --platform steam:macos --env prd --steam-manifest -``` - -The npm alias is `build:steam:manifest` (append `-- --env dev` for another environment). This command runs on any OS. -`--platform` selects the Vite configuration; all configured shared depots are combined. -It selects the last successful exports using `build.outDir` and `--env`, validating the App ID, Depot IDs, game name, executable name and version. -Missing packages cause exit code 1. Old combined VDFs are invalidated during regeneration. -Do not combine this command with `--arch` / `--preview` / `--build` / `--open`. - -`app_preview.vdf` validates file mappings, `app_build.vdf` uploads, and `depot_build.vdf` recursively maps folder contents. -`steam_appid.txt` is excluded from distribution. ContentRoot is relative to the VDF, so move a standalone depot's application -and `*-steampipe/` together; preserve the whole `dist/steam/` layout for shared depots. - -```text -steamcmd +login BUILD_ACCOUNT +run_app_build "/absolute/path/to/app_preview.vdf" +quit -steamcmd +login BUILD_ACCOUNT +run_app_build "/absolute/path/to/app_build.vdf" +quit -``` +1. Check that the BuildID in `dist/steam/uploads//-/upload-result.json` is active on the target Steamworks branch. Substitute your custom output root for `dist/steam` if applicable. +2. In the Steam client's Properties > Game Versions & Betas, enter the password and select `internal`. +3. Test installation, launch, exit, input, audio, fullscreen, offline launch and saves after updates on each OS. Test macOS Universal on both Intel and Apple Silicon. +4. Test advertised Overlay, Steam Deck and Linux support on hardware, matching the store listing. Achievements, DRM and Steam Cloud are not integrated automatically. -Ordinary exports and `--steam-manifest` omit `SetLive`; assign the uploaded build to its branch through Steamworks. -Each per-OS VDF updates one depot, so verify the final Build references the intended manifest version for every OS. -[Official SteamPipe workflow and VDF specification](https://partner.steamgames.com/doc/sdk/uploading) - -### Reference: Templates, host and migration - -`create-next2d-app` initializes `appId`, `appName`, `executableName` and `companyName` from the project name. -For example, `my-game` produces `app.example.my-game` for `appId` and `my-game` for the other three fields. -Replace the bundle ID and company name with your own values before distribution. -Missing CPU settings receive the defaults for each OS; values already provided by the template are preserved. -Other settings, such as icon paths and Steam IDs, are also preserved. - -The builder manages Electron host code. It stages the host, runtime configuration and web assets in an OS temporary directory, -then removes it after export, including failures. No `electron/`, Electron-specific `node_modules` or lockfile is created in the game. -Electron is pinned in `templates/electron/package.json`; Packager is pinned in `src/tool-packages.ts`. Both are downloaded and cached. -Packager is acquired only for Electron exports and handles OS packages, icons, signing and notarization. -The host has no npm dependencies or native addons, so ABI-specific rebuilding is unnecessary. -Preview exports for the host OS/CPU and launches the application under `dist//build//`. - -Legacy `electron/` host code, `config.forge` and custom npm dependencies are not used. -For migration, move icons into shared assets and update their JSON paths before deleting the old directory. -Custom main/preload code or native addons require builder support before migration. - -The template host loads assets using absolute paths and the fixed origin `next2d://game`. -Local fetch, Workers and localStorage work independently of the startup working directory. -F11/Alt+Enter enters fullscreen; Escape exits it. Closing the window also terminates the process on macOS. -Node integration is disabled, context isolation and sandboxing are enabled, and external navigation and new windows are blocked. -A Next2D CSP is applied. Games using external APIs must explicitly add their destinations. -[Electron security](https://www.electronjs.org/docs/latest/tutorial/security) / -[protocol](https://www.electronjs.org/docs/latest/api/protocol) - -Save data is stored in the `appId` directory under Electron's appData location. -Changing the display name does not change that location. Saves from older file-origin development builds are not migrated automatically. -Steam Cloud is not integrated. When adding it, design game-specific save files and per-account storage separately, -rather than syncing the entire Chromium profile. -[Steam Cloud](https://partner.steamgames.com/doc/features/cloud) - -### Pre-release validation - -In addition to STEP6's installation and launch checks, verify: - -- Exit behavior, offline launch and saved data after updates. -- Mouse/keyboard/controller input, resolution and fullscreen switching, audio and sleep/resume. -- Shift+Tab Overlay. Electron uses multiple processes, so verify actual behavior on each OS/GPU. - This export does not integrate the Steamworks SDK, achievements, DRM or Overlay APIs. - SDK integration is not required for Steam distribution. -- On Linux, check dependent libraries and sandboxing in the Steam Linux Runtime environment. - Do not use `--no-sandbox` as a distribution workaround. -- Steam Deck Verified requires a separate review. Producing a Linux package alone does not establish compatibility. - Test controller-only operation, text readability and display behavior on hardware. -- Before Steam's build review, verify that the supported operating systems and features advertised on the store match the application. - -[Steamworks API](https://partner.steamgames.com/doc/sdk/api) / -[Overlay](https://partner.steamgames.com/doc/features/overlay) / -[Linux development](https://partner.steamgames.com/doc/store/application/platforms/linux) / -[Steam Deck compatibility](https://partner.steamgames.com/doc/steamhardware/compat) / -[Build review](https://partner.steamgames.com/doc/store/review_process) +For failures, inspect SteamPipe logs in `dist/steam/uploads//cache//`. From 44fb0c3648502ce76d939ce7376540f1523c4cd1 Mon Sep 17 00:00:00 2001 From: ienaga Date: Sun, 27 Sep 2026 00:57:45 +0900 Subject: [PATCH 2/3] =?UTF-8?q?electron=E3=81=AE=E3=83=8D=E3=82=A4?= =?UTF-8?q?=E3=83=86=E3=82=A3=E3=83=96=E5=8F=96=E3=82=8A=E8=BE=BC=E3=81=BF?= =?UTF-8?q?=E3=82=92=E8=BF=BD=E5=8A=A0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 2 + docs/native-bridge.md | 154 ++++++++++++++++++++++++ docs/steam.md | 3 + examples/native-bridge/macos/main.swift | 41 +++++++ package-lock.json | 22 ++-- package.json | 9 +- src/electron-config.ts | 30 ++++- src/electron-host.ts | 18 ++- src/electron-native.ts | 82 +++++++++++++ src/electron.ts | 9 +- templates/electron/index.js | 30 ++++- templates/electron/native-bridge.cjs | 98 +++++++++++++++ templates/electron/preload.cjs | 11 ++ tests/electron-temp.test.ts | 34 ++++++ tests/electron.test.ts | 47 ++++++++ tests/native-bridge.test.ts | 123 +++++++++++++++++++ tests/native-prepare.test.ts | 35 ++++++ 17 files changed, 718 insertions(+), 30 deletions(-) create mode 100644 docs/native-bridge.md create mode 100644 examples/native-bridge/macos/main.swift create mode 100644 src/electron-native.ts create mode 100644 templates/electron/native-bridge.cjs create mode 100644 templates/electron/preload.cjs create mode 100644 tests/electron-temp.test.ts create mode 100644 tests/native-bridge.test.ts create mode 100644 tests/native-prepare.test.ts diff --git a/README.md b/README.md index 3841cca..c2e0033 100644 --- a/README.md +++ b/README.md @@ -32,6 +32,7 @@ Xbox対応は試作・開発段階です。 | ガイド | 内容 | |---|---| | [Electron / Steam](docs/steam.md#日本語) | デスクトップ書き出し、アイコン、CPU、署名、Steam Depot、アップロード、ベータテスト | +| [ネイティブ機能の拡張](docs/native-bridge.md) | OS API・任意SDKとの連携、設定、プロトコル、実装例（OS情報取得・EOS） | | [iOS / Android（Capacitor）](docs/capacitor.md#日本語) | ネイティブ設定、SDK、プラグイン、ビルドコマンド、移行、Xcodeの設定 | | [Xbox（試作）](docs/xbox.md#日本語) | 開発状況、ホスト生成、ビルド環境、検証範囲 | @@ -82,6 +83,7 @@ These guides cover platform-specific configuration, dependencies, builds and dis | Guide | Contents | |---|---| | [Electron / Steam](docs/steam.md#english) | Desktop exports, icons, architectures, signing, Steam depots, uploads and beta testing | +| [Native extensions (Japanese)](docs/native-bridge.md) | OS APIs and SDK integration, configuration, protocol, and examples (system information / EOS) | | [iOS / Android (Capacitor)](docs/capacitor.md#english) | Native configuration, SDKs, plugins, build commands, migration and Xcode setup | | [Xbox (prototype)](docs/xbox.md#english) | Development status, host generation, build environment and validation scope | diff --git a/docs/native-bridge.md b/docs/native-bridge.md new file mode 100644 index 0000000..3480c6c --- /dev/null +++ b/docs/native-bridge.md @@ -0,0 +1,154 @@ +# ネイティブ機能の拡張（Electron Native Bridge） + +Next2Dのデスクトップアプリから、OS APIや任意のネイティブSDKを利用するための汎用拡張です。EOS専用ではありません。ネイティブ機能はアプリ側が用意する実行ファイル（sidecar）に実装し、builderが起動・通信・同梱を担当します。 + +対象はElectronのmacOS／Windows／LinuxとSteamデスクトップ出力です。WebブラウザやiOS／AndroidにはこのAPIは提供されません。モバイルは [Capacitorガイド](capacitor.md) を参照してください。 + +## 責務と構成 + +```text +Next2Dアプリ → window.next2dNative → Electron IPC → ネイティブ実行ファイル + └ OS API / 任意のSDK +``` + +- builder: CPU別ファイルの同梱、メソッド許可リスト、要求／応答・イベント通信、プロセス終了処理。 +- アプリ: ネイティブ処理と入力検証、各OS向けコンパイル、SDKの初期化・後始末、ライセンスと権限設定。 +- SDKの取得、ソースの自動コンパイル、認証・オンラインサービスの実装はbuilderの機能ではありません。 +- `nativeBridge` 未設定ならプロセスを起動せず、`window.next2dNative` も公開しません。 + +## 1. ネイティブ実行ファイルを用意する + +SDK不要の例として、OS情報を取得する [Swift実装](../examples/native-bridge/macos/main.swift) を同梱しています。Apple Silicon MacでXcode Command Line Toolsが利用できる場合、ゲームプロジェクトのルートで実行します。 + +```sh +mkdir -p native/macos-arm64 +xcrun swiftc node_modules/@next2d/builder/examples/native-bridge/macos/main.swift -O -o native/macos-arm64/native-helper +``` + +ローカルのbuilderを使う場合はソースパスをその `examples/native-bridge/macos/main.swift` に置き換えます。このサンプルはmacOS用です。他のOSでは同じJSONプロトコルを実装した実行ファイルを用意します。使用言語はSwiftに限定されず、C++／Rustなどでも構いません。 + +## 2. electron.config.json に設定する + +既存のアプリ設定に追加します。 + +```json +{ + "architectures": { "macos": "arm64" }, + "nativeBridge": { + "methods": ["system.info"], + "backgroundThrottling": true, + "targets": { + "macos-arm64": { "directory": "native/macos-arm64", "executable": "native-helper" } + } + } +} +``` + +| 設定 | 内容 | +|---|---| +| `methods` | rendererから許可するメソッド名。英字開始、英数字・`_`・`.`、最大64文字 | +| `targets` | ビルドするOS・CPUに対応するネイティブファイル群 | +| `directory` | プロジェクトルート基準のディレクトリ。絶対パスも可能。全体を同梱 | +| `executable` | ディレクトリ直下の実行ファイル名。パスやシェルコマンドは不可 | +| `backgroundThrottling` | `true` は非アクティブ時のrendererの処理抑制を許可。リアルタイム用途では `false`。既存利用との互換性のため省略時は `false` | + +バックグラウンド設定はrendererのタイマー・描画の指定であり、OS全体の省電力設定やsidecarのスケジューリングを変更しません。 + +対応キーは `macos-arm64`／`macos-x64`／`macos-universal`／`windows-x64`／`windows-arm64`／`linux-x64`／`linux-arm64`。未用意のターゲットへの出力はエラーになります。macOS既定値はuniversalなので、上例はarm64を明示しています。universalは実行ファイルと依存ライブラリすべてが両CPU対応である必要があります。builderはCPU形式を検査・変換しません。 + +専用ディレクトリには実行ファイルと必要なdylib／DLL／so、配布可能なデータだけを置きます。ソース、秘密鍵、管理者資格情報を置かないでください。シンボリックリンクと特殊ファイルは拒否します。 + +## 3. Next2Dアプリから呼び出す + +```js +const native = window.next2dNative; +if (native) { + const unsubscribe = native.onEvent(({ event, data }) => { + if (event === "system.ready") console.log("Native helper ready", data); + if (event === "bridge.closed") console.error("Native helper closed", data); + }); + try { + const info = await native.request("system.info", {}); + console.log(info.platform, info.logicalProcessors); + } catch (error) { + console.error("Native request failed", error); + } finally { + unsubscribe(); // 継続監視する場合は画面・サービスの破棄時に解除 + } +} +``` + +`request(method, params)` は応答を返すPromise、`onEvent(listener)` は解除関数を返します。アプリの通信・デバイス操作層にラップし、UIとは分離してください。Node API・任意パス・汎用IPC・シェル実行はrendererへ公開しません。sandbox／contextIsolationを維持し、IPCはアプリのメインフレームに限定します。引数はsidecarでも検証してください。 + +## 4. ビルド・配布 + +```sh +npx @next2d/builder --platform macos --arch arm64 --env local --preview +npx @next2d/builder --platform macos --arch arm64 --env prd +``` + +ローカルのbuilderでは `npm run build` 後、ゲームプロジェクトから `node ../builder/dist/index.js ...` で実行できます。 + +ネイティブファイルはASAR外の `process.resourcesPath/native`（macOSでは `.app/Contents/Resources/native`）へ配置され、Web配信する `resources` とは分離されます。共有ライブラリは実行ファイル相対で解決できるようにビルドしてください。最初の `request` で同梱実行ファイルが起動します。 + +署名・公証は [デスクトップガイド](steam.md) の設定を使用し、実行ファイルと依存ライブラリを含む完成アプリで検証します。利用するOS機能に応じた説明文・権限・entitlement等は別途必要です。例えばLANアクセスでは `macos.localNetworkUsageDescription` を設定できます。単純なOS情報取得の例では必要ありません。 + +ビルド専用設定は `NEXT2D_ELECTRON_CONFIG_FILE=/absolute/path/to/config.json` で指定可能です。存在しない指定先はエラーになります。一時設定はアプリ側で管理し、配布ディレクトリには混ぜないでください。同梱ファイルを秘密にする保証はありません。 + +## Sidecarプロトコル v1 + +stdin／stdoutでUTF-8 JSONを1行ずつ交換します。stdoutはプロトコル専用とし、各行をflushしてください。 + +```json +{"id":1,"method":"system.info","params":{}} +{"id":1,"result":{"platform":"macos","logicalProcessors":8}} +{"id":2,"error":"Unsupported method"} +{"event":"system.ready","data":{"protocol":1}} +``` + +要求の整数IDを応答にそのまま返します。エラーは文字列の `error`、イベントは `event` と `data` を使います。`bridge.closed` はbuilder予約名です。業務エラーはその要求だけを失敗させます。 + +- 1行最大256KiB、同時要求128件、応答待ち15秒。SDK用途に固有のメソッドは予約しません。 +- タイムアウトはネイティブ処理のキャンセルではありません。再試行・重複防止はアプリ側で設計します。 +- プロトコル違反・プロセス終了で待機中の要求を失敗させ、`bridge.closed` を通知。自動再起動はしません。 +- ブリッジの終了処理はstdinを閉じ、EOFでsidecarの後始末を促し、4秒後の強制終了を予約します。ただしElectron本体を4秒間終了待ちにする仕組みではなく、本体が先に終了するとタイマーは実行されません。必ずstdin EOFで速やかに終了する設計にしてください。プロトコル違反等では即時強制終了します。rendererクラッシュ時も終了処理を行いますが、強制終了・OS異常時の後始末は保証できません。 +- 外部サービスの切断・保存等は必要に応じて終了前に独自のメソッドで行います。別の常駐プロセスを起動せず、stdin EOFでも終了するよう実装してください。 +- stderrは読み捨て、rendererには転送しません。必要な診断ログはsidecar側で秘匿情報を除いて記録します。大量のイベントは発行元で制限・集約してください。 + +現状は1アプリにつき1つのsidecarです。複数SDKを使う場合はその実行ファイル内でメソッドを振り分けます。動的な任意実行や複数プロセスのプラグイン管理機構ではありません。 + +## ビルド時の準備スクリプト（任意） + +`nativeBridge.prepare` にプロジェクト相対の `.js` / `.mjs` / `.cjs` を指定すると、通常のデスクトップ／Steam書き出しで、ネイティブ同梱前にNode.jsスクリプトを実行します。CLI・環境名・出力先は変わりません。未指定の場合は従来どおり `targets` のディレクトリ全体をコピーします。 + +```json +{ "nativeBridge": { + "prepare": "scripts/prepare-native.mjs", + "methods": ["system.info"], + "targets": { "windows-x64": { "directory": "native/windows-x64", "executable": "helper.exe" } } +} } +``` + +実行契約：`node