sunfish-shogi/Extension.md

## Extension.md

      
    Raw
  

              Extension.md
            
          
    拡張機能の概念

拡張機能の位置づけとライフサイクル


拡張機能はそのそれぞれが「対局」や「検討」「解析」に並ぶような位置づけであり、他の機能と同時に実行することはできない。
拡張機能は子プロセスとして実行され、コマンド引数と標準入出力によって Electron 将棋とやりとりをする。
1 回の機能利用開始から終了までが 1 プロセスの生存期間となる。

イベント

Electron 将棋は主にユーザーが起点となり発生したイベントを標準入力で拡張機能に通知する。
ただし、インタラクティブでない拡張機能では使用しない。
例

メニューボタンの押下
指し手の入力
局面の変更
コメントの編集

命令

拡張機能は標準出力によって命令を送る。
Electron 将棋はその命令に従い各種の処理を実行する。
例

メッセージの表示
入力フォームの表示
局面の変更
棋譜の変更
コメントの変更

画面


ファイル構成

/my-extension/extension-config.json
             /my-extension.exe (config から相対パスで指定するので別の場所でも良い)

設定ファイル

拡張機能は JSON の設定ファイルを持っており、 Electron 将棋はそれを起点に拡張機能を認識する。
つまり、ユーザーはファイル選択ダイアログでこの設定ファイルを選択することによって、拡張機能を登録できる。
{
  "name": "my-extension",
  "author": "kubo",
  "version": "v1.0.0",
  "protocol": {
    "version": 1 // 数値でよいのか？
  },
  "host": {
    "electronShogi": {
      "minimumVersion": "v1.4.0"
    },
  },
  "command": "./my-extension.exe",
  "arguments": [ "-usi", "{{position.usi}}", "-settings", "{{settings}}" ],
  "workingDirectory": ".", // shogi-extension-config.json からの相対パスで実行時のカレントディレクトリを指定
  "userSettings": {
    "foo": { "type": "bool", "name": "Foo" },
    "bar": { "type": "int", "name": "Bar" }
  },
  "interactive": true, // false の場合はプロセス終了までユーザー操作をブロックする。
  "events": { // 受信したいイベント（interactive が true の場合のみ使用できる。それなら interactive の指定が必要か？という話はあるかも。）
    "changePosition": {
      "with": ["position.usi"] // イベント発生時に受け取りたい情報
    },
    "menu": {
      "with": ["menu.id"], // 押されたメニューボタンの ID を受け取る。
      "menu": [ // 画面に表示するメニューボタン
        { "id": "search", "name": "検索" }
      ]
    }
    // "quit" イベントはここに書かなくても終了時に必ず送られる。
  },
  "format": "json" // しばらく一種類しかサポートしないと思うけど一応。
}
イベント

Electron 将棋から標準入力へ 1 イベント 1 JSON で送信する。
（1 イベント中の改行は無しにした方が良いかも）
{
  "type": "event", // 今のところ "event" 以外は考えていないが、将来のために入れておく。
  "eventCode": "changePosition",
  "values": {
    "usi": "position sfen lnsgkgsnl/9/ppppppppp/9/9/9/PPPPPPPPP/1B5R1/LNSGKGSNL w - 1 moves 5a6b 7g7f 3a3b"
  }
}
{
  "type": "event",
  "eventCode": "menu",
  "values": {
    "menu.id": "search" // 拡張機能側が設定で定義したメニューの ID
  }
}
命令

拡張機能から標準出力へ 1 命令 1 JSON で送信する。
（1 命令中の改行は無しにした方が良いかも）
{
  "type": "appendComment",
  "value": "【AIコメント】この手で34の銀を殺す手を見せつつ、飛車成りを狙っています。"
}
{
  "type": "displayMessageBox",
  "value": "【AIコメント】この手で34の銀を殺す手を見せつつ、飛車成りを狙っています。"
}