メインコンテンツまでスキップ

インストール

Desktop Homunculus のインストールと MOD 環境のセットアップ手順です。

システム要件​

macOSWindows
OSmacOS 12 (Monterey) 以降Windows 10 以降
CPUApple Silicon または Intelx86_64
Node.js22 以上22 以上
ディスク容量500 MB 以上500 MB 以上

Step 1: Desktop Homunculus のインストール​

GitHub リリースページから最新版をダウンロードしてください。

  1. .dmg ファイルをダウンロード
  2. DMG を開き、Desktop Homunculus を /Applications フォルダにドラッグ
  3. アプリケーションフォルダから起動
Gatekeeper の警告

「"Desktop Homunculus"は開発元を確認できないため開けません」と表示された場合:

  1. システム設定 > プライバシーとセキュリティ を開く
  2. 下にスクロールし、このまま開く をクリック
  3. 確認ダイアログで 開く をクリック

Step 2: Node.js のインストール​

Desktop Homunculus の MOD は tsx を使用して TypeScript スクリプトを直接実行するため、Node.js 22 以上 が必要です。

  1. Node.js ダウンロードページにアクセス
  2. LTS バージョン（22 以上）をダウンロードしてインストール
  3. インストールを確認:
node -v

v22.0.0 以上が表示されれば OK です。

ヒント

すでに Node.js がインストールされている場合は node -v でバージョンを確認してください。v22 未満の場合は最新の LTS バージョンに更新してください。

Step 3: MOD 管理ツールのインストール​

pnpm（パッケージマネージャー）と @hmcs/cli（MOD 管理 CLI）をグローバルインストールします:

npm install -g pnpm @hmcs/cli

インストールを確認:

pnpm -v
hmcs --version
権限エラー

EACCES 権限エラーが出た場合は、npm のドキュメント（権限エラーの解決方法）を参照してください。

Step 4: 公式 MOD のインストール​

推奨される公式 MOD をインストールします:

hmcs mod install @hmcs/assets @hmcs/elmer @hmcs/menu @hmcs/character-settings @hmcs/settings @hmcs/app-exit
MOD説明
@hmcs/assetsデフォルトのアニメーションと効果音
@hmcs/elmerデフォルトのキャラクターモデル
@hmcs/menu右クリックコンテキストメニュー
@hmcs/character-settingsキャラクターごとの設定パネル
@hmcs/settingsシステムトレイからのアプリケーション設定（フレームレート、影の不透明度）
@hmcs/app-exitシステムトレイの終了メニュー

Step 5: 動作確認​

  1. Desktop Homunculus を起動
  2. デスクトップにキャラクターが表示される
  3. キャラクターを右クリックしてコンテキストメニューが開く

すべて正常に動作すれば、セットアップ完了です!

次のステップ

クイックスタートガイドに進んで、キャラクターとの基本的なやり取り方法を学びましょう。

トラブルシューティング​

hmcs: command not found​

ターミナルが hmcs コマンドを認識できていません。

  • ターミナルを再起動してください — PATH が更新されていない可能性があります
  • npm のグローバル bin ディレクトリが PATH に含まれているか確認: 
    npm bin -g

Node.js のバージョンが 22 未満​

MOD は tsx を使用して TypeScript を直接実行するため、Node.js 22 以上が必要です。nodejs.org から最新の LTS バージョンをダウンロードしてください。

Gatekeeper でアプリがブロックされる​

Step 1の手順を参照してください。

Windows でウィンドウの背景が黒い/不透明になる​

Windows でウィンドウの背景が透明にならず黒く表示される場合、NVIDIA GPU の設定変更が必要です。Step 1 の NVIDIA GPU の設定手順（Windows タブ）を参照してください。

MOD インストール後にキャラクターが表示されない​

Desktop Homunculus を再起動してください。MOD の変更はアプリの再起動後に反映されます。

MOD のインストールに失敗する​

ネットワーク接続を確認して再試行してください。