自作プラグイン/custommap の履歴(No.11)

インタラクティブマップ作成プラグイン

custommap.inc.php
製作者	kanateko
バージョン	1.10.0
動作確認	PukiWiki 1.5.4 - 1.5.4
最終更新	2026-03-16

タイル画像を使用したインタラクティブマップを表示し、指定した位置にカスタムマーカーを設置できるプラグイン。ゲームの攻略マップなど、カスタム画像上に任意のマーカーを配置できる。

プラグインの特徴

🗺 タイルベースマップ：ズームレベル対応のタイル画像表示
📌 カスタムマーカー：アイコンの種類や背景ピンの色をカスタマイズ可能
🔍 洗練されたUI：ズームコントロール、タブ形式のドロワーメニュー、各種ツール
📺 全画面モード：マップをブラウザ画面いっぱいに広げて表示可能（Escキーで解除）
📱 レスポンシブ・タッチ対応：PC・モバイル（ピンチズーム・スワイプ）に両対応
🌙 ダークモード：PukiWikiのダークテーマ設定と自動同期
🏷 ラベル常時表示：ズームレベルに関わらず全マーカーのラベルを常に表示可能
🔍 マーカー検索：大量のマーカーから名前や説明で目的のものを素早く検索
🔗 マーカー共有リンク：マーカーのURLやIDのコピー、マーカーへのリンク設置が可能
📋 座標コピー：マップ上をクリックして ||x|y||| 形式（プラグインの引数と同じ形式）で座標をクリップボードにコピー
💾 状態の保存：フィルターや表示設定をブラウザ（LocalStorage）に保存し、再訪時も維持
✏️ 説明文の直接編集：ツールチップ上のアイコンからマーカーの説明文を直接編集・保存可能（権限がある場合のみ）
🛠 デバッグ機能：座標確認、原点軸描画、マーカー座標表示など、マップ作成を支援するツール

動作環境

PukiWiki 1.5.4 以降
PHP 8.2 以降
モダンブラウザ（ES2022対応）

ダウンロード

このプラグインは現在公開されていません。

日付	バージョン	備考
2026-03-16	1.10.0	focus引数の追加 marker-data引数の追加デバッグ関連リンクの拡張
2026-03-15	1.9.1	レンダリングエンジンの大幅な最適化データ読み込みの効率化
2026-03-15	1.9.0	ツールチップからのマーカー説明文編集機能の実装座標取得モードにおけるマーカー名選択機能の追加
2026-03-14	1.8.5	インラインリンクのハイドレーション対応
2026-03-14	1.8.4	ドロワーのアイコン拡大と表示順序の調整
2026-03-13	1.8.3	マーカーフォーカス時のズーム挙動改善マーカー非表示時の残存バグ修正すべて非表示状態の保存失敗を修正
2026-03-12	1.8.2	常時ラベル表示時のレンダリングを修正
2026-03-12	1.8.1	重複スタイルの挿入防止同位置マーカー展開時のホバー挙動修正ズームUI非表示時のツール位置調整フルスクリーンボタンのアイコン動的切り替えドロワー閉じるボタンのSVG化
2026-03-11	1.8.0	全画面モードの実装ツール表示設定のリファクタリング（一括制御に対応）読み込み中オーバーレイ（ローダー）の追加
2026-03-11	1.7.0	レンダリングの最適化による大幅なパフォーマンス向上
2026-03-10	1.6.1	同座標マーカーの展開表示機能の実装マーカー画像未指定時の描画改善 (白丸表示) マーカーフォーカス時の自動スクロールとツールチップ解消
	1.6.0	マーカー共有リンク機能の実装 (URLコピー・インラインリンク・固定ID対応) マーカーホバーアニメーションの平滑化
	1.5.1	ドロワー内設定のアコーディオン化座標取得ボタンのダークモード対応修正設定UIの操作性改善座標取得時の情報更新改善表示制御・操作干渉の修正
2026-03-09	1.5.0	座標コピー機能の追加ズームUIの表示設定機能の追加デバッグモード時のマーカー座標表示を追加
	1.4.1	状態の永続化 (LocalStorage) への対応カテゴリトグル動作の改善
	1.4.0	データ読み込み方式の刷新（非同期ロード）パフォーマンスの更なる向上
2026-03-07	1.3.2	ドロワーUIの刷新（タブ形式化）ラベル常時表示機能の追加デバッグ項目の整理
	1.3.1	ズームボタンの無効化処理ズーム時の点滅軽減
	1.3.0	Canvas描画によるパフォーマンスの劇的改善大量マーカー表示の最適化
	1.2.1	テーマ切り替えUIの改善ドロワー内アイコンの修正
2026-03-06	1.2.0	マーカー機能の拡張 (SVGピン対応など) ドロワーUI・デバッグモードの改善
2026-03-05	1.1.0	スムーズなズーム遷移ズームコントロールUIの追加
2026-03-04	1.0.0	初版作成

プラグイン設定

設定ページは :config/plugin/custommap/{設定名} に作成する。

各種設定項目

設定ページ内のオプション
-dir	string	なし	ディレクトリモードでのタイル画像ディレクトリ名
-attach	string	なし	添付ファイルモードでの読み込み元ページ名
-tileSize	string	'256x256'	各タイル画像のピクセルサイズ。`256`の場合は`256x256`と同じ意味
-imageSize	string	自動計算	初期表示の全体画像のサイズ。省略時はtileSize×tileCount
-mapSize	string	自動計算	座標系のサイズ
-origin	string	'0,0'	座標 (0,0) の位置。デフォルトでは画像の中心が (0,0)
-invertY	bool	true	true: Y軸が下方向に増加（UE座標系）
-center	string	origin	初期表示の中心座標
-zoom	int	0	初期ズームレベル

-dirと-attachはどちらか一方のみ指定可能。
どちらの指定もない場合は、-attach:{設定ページ名} と同じ動作をする。

-dirで指定した場合は、image/{dir}内の画像がタイル画像として使用される。

例えば-dir:mapを指定した場合、image/map/{z}/{x}/{y}.{ext}の形式で画像が配置されている必要がある。

ディレクトリ構造例

image/
└── map/                  (← -dir で指定した名前)
     ├── 0/               (← Z座標/ズームレベル)
     │    └── 0/         (← X座標)
     │         └── 0.png (← Y座標)
     └── 1/
          ├── 0/
          │    ├── 0.png
          │    └── 1.png
          └── 1/
               ├── 0.png
               └── 1.png

-attach::config/plugin/custommap/mapで指定した場合は、:config/plugin/custommap/mapに添付された{z}_{x}_{y}.{ext}の形式の画像がタイル画像として使用される。
添付ファイル例
```
:config/plugin/custommap/map
 ├── 0_0_0.png
 ├── 0_0_1.png
 ├── 0_1_0.png
 ├── 0_1_1.png
 ├── 1_0_0.png
 ├── 1_0_1.png
 ├── 1_1_0.png
 └── 1_1_1.png
```

マーカー定義

設定ページ内にテーブル形式でマーカーの定義を記述する。

|マーカー名|アイコン画像|カテゴリ|マーカー色|サイズ|デフォルトラベル|デフォルト説明|

列	必須	説明
マーカー名	✅	プラグイン記述で使用する識別名
アイコン画像		添付ファイルのパスまたは相対パス。省略時は表示なし
カテゴリ		フィルターでのグループ名。省略時は「その他」
マーカー色		SVGピンアイコンの背景色 (例: `#FF5A3C` や `red`)。省略時は■`#2B3344`
サイズ		アイコンの表示サイズ (`WxH` または単一数値)。省略時は`20x20`
デフォルトラベル		プラグイン記述で省略された場合に使われるラベル。省略時はマーカー名を使用
デフォルト説明		プラグイン記述で省略された場合に使われる説明 (PukiWiki構文使用可)

※ ヘッダー行（末尾h）やスタイル行（末尾c）は自動的に無視される。

使用方法

ブロック型でインタラクティブマップを設置する。

#custommap(設定名 [, class=追加クラス, focus=ID, marker-data=ページ名]){{
|マーカー名#ID|X座標|Y座標|ラベル|説明|
|マーカー名|X座標|Y座標|||
}}

※ IDは任意で設定可能。省略した場合は自動生成される。

インライン型では、マーカーへのリンクを設置できる。

&custommap(ID){リンクテキスト};

引数一覧

ブロック型で使える引数。

引数名	説明	例
`設定名`	設定ページ名 (`:config/plugin/custommap/`以降)	`#custommap(swamp)`
`class=`	wrapperに追加するCSSクラス名（複数指定可）	`class=wide-map dark-border`
`focus=`	初期表示時にフォーカスするマーカーID	`focus=marker_01`
`marker-data=`	マーカー座標データを読み込む外部ページ名	`marker-data=MapMarkers`

marker-data はマルチライン部分での座標指定と併用可能。
- 複数のページで同じ座標データを共有したい場合などに使用する。
- 指定先のページでは、マルチライン部分と同様に|マーカー名#ID|X座標|Y座標|ラベル|説明|の形式で座標データを記述する。

使用例

以下はデモ用に適当に作ったマップデータになる。タイル画像はズーム2段階分用意してある。

本格的な使い方が見たい場合はこのページを参照。

マーカーへのリンク → 展開表示デモ他のページから読み込んだマーカー

ページの編集権限がある場合は、以下の画面のようにツールチップの編集を行うことができる。

技術的メモ

マップの描画やインタラクション機能はTypeScriptで自作しており、外部ライブラリは使用していない。
WebGLによるインスタンス描画をメインエンジンとして採用。数万個のマーカーが存在する場合でも、GPU頂点シェーダー側で座標計算（マップ座標→ビューポート座標）を行うことで、マップ移動時のCPU負荷を最小限に抑え、スムーズな描画を実現。
WebGLが利用できない環境向けに、Canvas2Dによる高速なフォールバックも維持。
PHP側では設定ページの解析、JSONへのデータ変換、初期HTML構造の出力のみを行う。
フィルター状態やテーマ設定などはLocalStorage（custommap_state_*）に保存される。
ゲームのマップを作成することを前提にしているので、Y軸は下方向に増加（UE座標系）し、座標(0,0)をマップの中心に配置するようにしている。

Loading comments…