(keymap-duplicates)=

# 削除したはずのPMEキーマップが残り続ける(重複・ゴーストキーマップ)

```{important}
- 「削除したはずのPMEキーマップが、Blender再起動後に戻ってくる」
- 「PMEをアンインストールしたのに、空のPMEエントリが残っている」
- 「Keymap設定に `Call Menu (PME)` が何重にも並んでいる」

これらの症状は**PME単独の不具合ではなく、BlenderのKeymap Export/Importが層構造を
潰すという上流の仕様**が原因で起きます。キーマップを多く登録する性質上、PMEで
表面化しやすくなっています。

掃除したいだけなら [復旧](#keymap-duplicates-recovery) を、再発を避けるには
[予防](#keymap-duplicates-prevention) を参照してください。
```

## こんな症状はありませんか？

次のいずれかに当てはまる場合、このページが扱う現象です。

- **Preferences > Keymap** を開くと、同じホットキーの `Call Menu (PME)` が何行も並んでいる
- 重複行を手で削除しても、**Blender再起動後または設定保存時に復活する**
- **PMEアドオン自体を無効化・削除しても、空のPMEエントリが残り続ける**
- キーマップを触った覚えがないのに、**他のアドオン・標準機能のホットキーがPMEに奪われたように動かなくなった**
- Keymap Editorで、パイメニュー名などの情報が空欄になっている「空のPMEエントリ」がある

コミュニティでは "ghost keymaps" と呼ばれ、長く議論されてきた現象です。

## これはPME固有の不具合ではありません

同じ仕組みでキーマップを登録するアドオンなら同様に起きうる、**Blender側の
キーマップシステムの設計に由来する問題**です。PMEはパイメニュー・ポップアップなど
多数のキーマップを扱うため、他のアドオンより症状が目立ちやすくなっています。

## なぜ起きるのか

### BlenderのKeymapは4層構造

BlenderはKeymapを4つの層で管理しています。

:::{list-table}
:header-rows: 1
:widths: 18 52 15

* - 層
  - 役割
  - 保存される?
* - **default**
  - 工場出荷時の設定(リセット時の復元先)
  - —
* - **active**
  - 現在のプリセット(`userpref.blend` に保存)
  - ✅
* - **addon**
  - アドオンが登録するキーマップ。Blender起動ごとに再構築される
  - —
* - **user**
  - UIに見えるもの = active + addon を合成した結果。<br>ユーザー編集は**差分**として保存され、起動時に再合成される
  - (差分のみ)
:::

この層構造があるからこそ、「アドオンのキーマップ」「ユーザーのカスタマイズ」
「工場出荷状態へのリセット」を共存させられます。

### Export/Importがこの層構造を潰す

`Preferences > Keymap` の **Export Key Configuration** / **Import Key Configuration**、
および **Save as Preset**(プリセット保存)を実行すると、Blender は内部的に次の処理を行います。

1. **user**層で **どれか1つでも編集されているKeyMap**(`km.is_user_modified = True`)を
   ピックアップする
2. そのKeyMapに含まれる**すべての項目をコピー**する(アドオン由来の項目も区別なく)
3. コピーを **active**層に焼き付ける

問題は **2** です。フラグはKeyMap単位で立つので、**たった1つのキーを編集しただけで、
そのKeyMap内のアドオン登録項目もまとめて「ユーザー設定」として保存**されてしまいます。

### 再起動のたびに重複が積み上がる

アドオン(PMEを含む)は、Blender起動時に自分のキーマップを **addon**層に登録し直します。
しかし上の手順で焼き付けられたコピーは、すでに **active**層に残っています。

結果として同じキーマップ項目が `active` と `addon` の**両方に存在**し、
`user` 層の見た目で**重複**として現れます。Export/Import やプリセット切り替えを繰り返すと、
この重複がさらに積み重なります。

### ゴースト(空の項目)はなぜ消せないのか

PMEは自分で登録したキーマップを削除するとき、`idname` とプロパティ値の組み合わせで
対象を識別しています。ところがExport/Importを経由すると、**プロパティ情報が欠落して
`is_property_set()` が機能しない項目**が生まれることがあります。

この状態になると、PMEはその項目を「自分が登録したもの」と認識できず、自動削除の対象に
なりません。これが「PMEアドオンを外してもゴーストだけが残る」理由です。

(keymap-duplicates-recovery)=
## 復旧

### ステップ1: Keymap Doctor でスキャンする

**Preferences > Settings > Hotkeys** の **Keymap Doctor** では、空のPMEキーマップ項目、
`active` keyconfig に混入した PME 項目、PME Hotkey と現在有効な Blender キーマップとの
競合を観測できます。

まずは **Scan Keymaps** を実行してください。

検出結果は次のように表示されます。

- 空のPME項目の総数
- 影響を受けているキーマップ数
- どの layer に存在するか
- 件数が多いキーマップ名
- `active` keyconfig に PME 項目が存在するか
- 同じキーマップ内で競合する Hotkey と相手の operator
- PME dispatcher が Hotkey Mode・CHORD・mouse modifier で振り分ける重複の件数
- 判定を完了できなかった Hotkey の件数

必要なら **Copy Summary** で匿名化済みの概要をクリップボードへコピーし、
**Open Report Folder** でローカル詳細レポートの保存場所を開けます。詳細レポートには
メニュー名や内部識別情報が含まれるため、外部へ共有する前に内容を確認してください。

スキャンは観測専用です。検出した Hotkey の割り当てや競合相手を自動的に変更・削除しません。

```{important}
問題の切り分けに役立つので、可能なら **Clean Up Empty Items** を押す前に
**Copy Summary** の内容を support / forum へ提出してください。詳細レポートが必要な場合は、
内容を確認したうえで共有してください。
```

### ステップ2: `Clean Up Empty Items` で削除する

スキャン結果で空のPME項目が見つかったら、**Clean Up Empty Items** を実行します。

この操作は、**プロパティが空だと断言できる `wm.pme_user_pie_menu_call` 項目だけ**を
保守的に削除します。通常のPMEホットキーや、意味の読み取れる項目までは触れません。

過去の事例では、1回の cleanup で**279件**の空PME項目が削除された報告があります。
症状が軽いうちは数件、放置した環境では数百件になることがあります。

### ステップ3: 変更を定着させる

cleanup で削除した結果は、**保存しないと再起動時に戻ってくる**ことがあります。
まずは次を試してください。

- **Preferences** > 左下のハンバーガーメニュー > **Save Preferences**

これで定着すれば完了です。

```{caution}
もし Save Preferences では再起動時に元に戻ってしまう場合、ユーザー報告では
**一度だけ Export → Import を行う**ことで定着したケースがあります。

ただし Export/Import はこの問題の**原因でもある**ので、掃除直後のワンショットに
限定し、以降は使わないでください。
```

### ステップ4: それでも解決しないとき

重複が深く絡み合っている場合、設定フォルダをクリーンにする方が早いことがあります。

1. PMEの設定をPME側のエクスポート機能でバックアップする
2. Blenderを終了する
3. Blenderの **config** フォルダを別名に退避(またはバックアップしてから削除)
4. Blenderを起動してクリーン状態から再セットアップ
5. 必要な設定をインポートし直す

設定フォルダの場所は、`File > Defaults > Show Preferences Location` などで確認できます。

### 古いPMEを使っている場合: legacy script を使う

PME にまだ Maintenance セクションが無い版では、以前の救済スクリプト
`pme_keymap_cleaner.py` を使う方法があります。

- <https://gist.github.com/Pluglug/d4246140ab5689373becc11d5353221a>

このスクリプトは PME 内部ユーティリティを使うため、**PMEがインストール・有効化されている
状態で実行**してください。PMEを先にアンインストールしてしまった場合は、一度再インストール
してから実行する必要があります。

(keymap-duplicates-prevention)=
## 予防

一度掃除したら、再発させないための運用に切り替えるのが重要です。

### 1. BlenderのKeymap Export/Importを原則使わない

最大の予防策は、**Blender標準の Keymap Export / Import を使わない**ことです。
**Save as Preset**(プリセット保存)も同じ仕組みで動作するため、同様に避けてください。

一度実行すると、以降の起動ごとに重複が発生し続ける可能性があります。

### 2. どうしてもエクスポートしたいとき: アドオンを一時的に無効化する

環境の引っ越しなどで本当にKeymapをエクスポートしたい場合は、**PMEと、キーマップを
登録する他のアドオンを一時的に無効化してから**エクスポートしてください。

こうすることで、アドオン由来のキーマップが `active` 層に焼き付くのを防げます。
インポート先でも同様に、アドオンを有効化する前にインポートしてください。

### 3. PMEのマクロを「ショートカット管理の窓口」にする

作者が推奨する運用として、**PMEのマクロ機能を代理キーマップ(Proxy Keymap)として
使う**方法があります。

- Blender標準のKeymapを直接編集するのではなく、**PMEのマクロとしてショートカットを定義**する
- そのマクロに PME 側でホットキーを割り当てる
- Blenderの Keymap 設定はほとんど触らないまま運用する

この運用にすると、環境を移行するときも **PMEの設定だけをエクスポート**すれば
済むため、Blender側のKeymap Export/Importを回避できます。

```{note}
代理キーマップは PME の処理が挟まるので、呼び出しごとに微小なオーバーヘッドが
発生します。パフォーマンスが厳しい操作には、カスタムアドオンとして実装するなど
別の手段を検討してください。
```

### 4. アドオンのホットキーをUIから削除しない

これは別の落とし穴ですが、同じ文脈でよく踏まれるので記載します。

Keymap Editorからアドオン登録のホットキーを削除すると、Blenderは**「削除した」
という差分を永続保存**します。

このため、次のような不思議な現象が起きます。

1. アドオンが同じホットキーを3つ登録
2. UIから3つとも削除する
3. Blender再起動
4. アドオンが同じホットキーを3つ登録 — **どれもKeymap Editorに現れない**(削除差分が残っているため)
5. 同じホットキーを4つ目として登録 — ようやく現れる

不要なアドオンホットキーは**削除せず、チェックを外して無効化**するのが安全です。

## 関連

- [キーマップの選び方](keymap_guide.md) — Keymapの選び方と探索順の基本
- [`pme_keymap_cleaner.py` (Gist)](https://gist.github.com/Pluglug/d4246140ab5689373becc11d5353221a)