# コンポーネント引数
# 概要
- すべて
sp_で始まる - Function 型は
_fnで終わる - Web Components 経由の場合、複雑な型は使えない
- Hash 型などは JSON5 風の文字列として指定する
- 内部で JSON5 形式としてパースする
- Hash は正確には Object 型のこと
# Level 1
# sp_mode
Type: view | play | edit
Default: view
モード
| 値 | 意味 | 用途 |
|---|---|---|
| view | 再生 | 棋譜を再生するときに使う |
| play | 操作 | CPUとの対戦や、一連の指し手で棋譜を作成するのに使う |
| edit | 編集 | 詰将棋や課題局面の作成に使う |
# sp_body
Type: String
Default: null
盤面に反映する棋譜を指定する。
- SFEN, KIF, BOD に対応する
- 棋譜のコンテンツを渡す (URLではない)
- 再生モード専用ではない
- モードに関係なく sp_turn と合わせて盤面を変化させるのに使う
- 不整合な形式の棋譜を渡してもエラーを出したりはしない
- 何が起きるかわからないので本当に正しい形式だけを渡してほしい
# sp_turn
Type: Integer
Default: -1
開始局面を指定する。
- 棋譜には表示したい局面のの情報が含まれていないためこれで指定する
- 負の値は最終局面から数えた局面になるため -1 は一番最後(終了図)の局面になる
- 例えば -2 は終了図の1つ過去の局面になる
# sp_viewpoint
Type: black | white
Default: black
視点
- 後手または上手視点にするには
whiteを指定する .sync対応
| 値 | 視点 |
|---|---|
| black | ☗ |
| white | ☖ |
See also: sp_active_side_viewpoint
# sp_controller
Type: Boolean
Default: false
コントローラーを表示するか?
- 局面を変更するボタンが合わさったコンポーネントのこと
See also: sp_slider, sp_overlay_nav
# sp_slider
Type: Boolean
Default: false
スライダーを表示するか?
- 再生モード時には表示しておくと指定の局面に移動しやすい
- 操作モード時にも表示できるけどガチ対局するときは消しておいた方がよい
- 編集モード時には設定に関係なく表示しない
See also: sp_controller, sp_mounted_focus_to_slider
# sp_piece_variant
Type: invisible | nureyon | paper | zuan | portella
Default: nureyon
駒の種類
- SVG な駒はどんなに巨大化してもぼやけない
- PNG な駒も元の解像度が高いので拡大してもそれほど気にならない
| 値 | 名称 | 表示 | 形式 | 影 | 特徴 | 推奨 サイズ |
|---|---|---|---|---|---|---|
| invisible | 透明 | 見えない | ||||
| nureyon | ぬれよん | SVG | ゴシック体の一文字 | 0.9 | ||
| paper | 紙面風 | SVG | 明朝体・裏面赤 | 0.8 | ||
| zuan | 図案駒 | PNG | ユニバーサルデザイン | 0.95 | ||
| portella | Portella | PNG | ✅ | 美麗 | 1.0 |
WARNING
種類と大きさは別の設定になっているため、必ず種類に合わせて次のCSS変数で大きさを調整すること。
- --sp_board_piece_size: 盤上の駒
- --sp_stand_piece_size: 持駒
- --sp_piece_box_piece_size: 駒箱の駒
See also: --sp_board_piece_size, --sp_stand_piece_size, --sp_piece_box_piece_size
# sp_board_variant
Type: none | wood_normal | wood_bright | wood_alpha | wood_opaque | emboss_alpha | emboss_opaque | mottled_stone | brushed_steel | japanese_paper | ghost_text
Default: none
盤のテクスチャ
- 基本なしでよい
- そのとき盤面の色は
--sp_board_colorで変更できる - 「○○効果」のものは半透明なので
--sp_board_colorとの組み合わせて使うのを想定している
| 値 | 名称 | 表示 | 形式 | 特徴 | おすすめ度 |
|---|---|---|---|---|---|
| none | なし | ◎ | |||
| wood_normal | 普通の木目 | png | ◎ | ||
| wood_bright | 明るい木目 | png | ○ | ||
| wood_alpha | 木目効果 | svg | 半透明 | ○ | |
| wood_opaque | 木目盤 | svg | ◎ | ||
| emboss_alpha | 凹凸効果 | svg | 半透明 | △ | |
| emboss_opaque | 凹凸盤 | svg | △ | ||
| mottled_stone | 斑石板 | svg | △ | ||
| brushed_steel | 研磨痕 | svg | △ | ||
| japanese_paper | 和紙 | svg | 実験的 | × | |
| ghost_text | 透かし盤 | svg | 実験的 | × |
WARNING
異なる種類の駒と盤の組み合わせに注意すべし。 デフォルメタイプとリアルタイプの組み合わせは最悪である。 例えばデフォルメタイプの「ぬれよん」とリアルタイプの「木目盤」の組み合わせは違和感が大きい。 つまり駒を「ぬれよん」にしたのであれば背景はなしの単色でよいし、盤を「木目盤」にしたなら、駒は「Portella」にすべきである。
See also: --sp_board_color
# Level 2
# sp_layout
Type: horizontal | vertical
Default: horizontal
駒台・名前・時間の表示場所を決める。
| 値 | 配置 | |
|---|---|---|
| horizontal | 横長 | デスクトップ向け |
| vertical | 縦長 | スマホ向け |
See also: sp_mobile_vertical
# sp_mobile_vertical
Type: Boolean
Default: true
画面幅が狭いとき自動的に上下配置に切り替えるか?
初期値を左右配置にしているときに関係してくる。 言い替えると「画面幅が広いときに左右配置に切り替えるか?」の設定でもある。
See also: sp_layout
# sp_preset
Type: String
Default: null
手合割(初期配置)の指定 非推奨
sp_mode="edit"と合わせてsp_preset="詰将棋"とすれば相手玉だけがある状態で始まるsp_bodyがあるのでこのパラメータは要らない
# sp_overlay_nav
Type: Boolean
Default: false
再生モードのときの盤上の左右をクリックして局面を動かせるようにするか?
- 有効にすると再生しやすくなるが駒を動かせなくなる
- 天王山をクリックすると反転する
- 基本的に盤面の中の操作トリガーはタッチした瞬間に反応する
pointerdownイベントに統一しているがsp_overlay_navはsp_controllerの代替機能でもあるため、例外的にclickイベントに反応するようにしている - また
clickイベントにすることでタッチスクロールが可能になる
See also: sp_controller
# sp_coordinate
Type: Boolean
Default: false
座標を表示するか?非推奨
WARNING
このオプションはまったくおすすめしない。 座標は左上が基点であることを知っていればよいだけであり、わざわざ表示するのはシンメトリーな美しさを台無しにする。 言わばロードバイク等を含めた自転車すべてに補助輪をつけるようなものである。
# sp_coordinate_variant_h
Type: kanji | number | alphabet
Default: kanji
上に表示するX座標表記
| 値 | 表記 |
|---|---|
| number | 1..9 |
| kanji | 一..九 |
| alphabet | a..i |
See also: sp_coordinate_variant_v
# sp_coordinate_variant_v
Type: kanji | number | alphabet
Default: number
右に表示するY座標表記
See also: sp_coordinate_variant_h
# sp_star_step
Default: 3
星をX個ごとに表示する。
# sp_stand_gravity
Type: bottom | top
Default: bottom
駒台を左右に配置したとき位置は上か下か?
下に寄せた方が対角線的に綺麗な配置に見える。 一方、右上だけで詰将棋を作るなら上に寄せた方が持駒が見やすくなるなどの利点もある。
| 値 | 寄せる方向 |
|---|---|
| bottom | 下 |
| top | 上 |
# sp_stand_flip
Type: Boolean
Default: false
相手側を反転するか?
| 値 | 意味 |
|---|---|
| false | 上下左右対象 (おすすめ) |
| true | 相手側の持駒も自分目線になる |
# sp_name_direction
Type: horizontal | vertical
Default: horizontal
名前の縦横書き切り替え
左右配置時のみ有効になる。 紙面風にしたいときかつ「先手」「後手」とだけ表記するなら縦書きにするのがてっとり早い。
| 値 | 意味 |
|---|---|
| horizontal | 横書き |
| vertical | 縦書き |
# sp_player_info
Type: Hash
Default: null
対局者と時間の情報をハッシュ形式で渡す。
例:
{
black: {
name: "六代大橋宗銀",
time: "12:34"
},
white: {
name: "伊藤印達",
time: "56:78",
},
}
# sp_turn_show
Type: Boolean
Default: false
再生モード時に手数の表示をするか?
- 盤の上部に表示する
- それをクリックすると入力フィールドに切り替わって局面(手数)を入力できる
- しかしこれまでの経験からしてあまり使うことはなかった
- スライダーを表示していれば現在の手数がわかるからというのもある
- スマホの場合、無駄に一行分画面を使ってしまう
# sp_active_side_viewpoint
Type: Boolean
Default: false
起動時に手番側の視点にするか?
言い替えると「指定の局面の手番が☖なら反転するか?」という意味になる。
See also: sp_viewpoint
# sp_comment
Type: Boolean
Default: true
KIF形式の棋譜にコメントが含まれていれば盤の下に表示するか?
- コメントがない場合には表示しない
- したがって全体を画面の中心に配置したい場合にはコメントの有無で盤の位置が変動してしまうという問題がある
# sp_human_side
Type: none | both | black | white
Default: both
操作モードで操作できる側を制限する。
- 自分が先手でCPUが後手だったとき both だと後手の考慮中に先手が後手の駒を動かせてしまう
- そんなとき black に変更しておけば先手は後手の駒を動かせなくなる
- つまりCPUと対戦するときの人間側を指定しておけばよい
| 値 | 操作できる側 |
|---|---|
| none | なし |
| both | ☗☖ |
| black | ☗ |
| white | ☖ |
# sp_balloon
Type: Boolean
Default: true
対局者名の下に駒数スタイルと同じ背景色を置くか?
# sp_board_variant_to_stand
Type: Boolean
Default: false
盤の種類を駒台にも適用するか?
# Level 3
# sp_lift_cancel_action
Type: standard | reality | rehold
Default: standard
盤上の持ち上げた駒のキャンセル方法
- 共通してマウスの右クリックやキーボードのESCキーでもキャンセルできる
- もともとリアル志向を初期値としていたが将棋ウォーズに慣れきってしまった者たちにはハードルが高かったため初期値を変更した。が、やっぱり戻すかもしれない
- 持駒にも同じ挙動を適用するべきだができていない
| 値 | 挙動 | タイプ |
|---|---|---|
| standard | 初心者向け 移動できないセルに移動したとき | 将棋ウォーズ ぴよ将棋 |
| reality | リアル志向 元の位置に戻す | 昔の共有将棋盤 |
| rehold | 合理的 キャンセルと同時に駒を持つ | lishogi |
TIP
lishogi の方法は常に駒を持った状態になってしまって駒を離せないので使いにくい仕様だと見ていたが、よく考えてみればこれから何かの手を指そうとしているときに、駒を持ち替えることはあっても、駒を離した状態に戻らないといけなくなることはないので、実はとても合理的な仕様だった。
# sp_view_mode_piece_movable
Type: Boolean
Default: true
再生モードでも駒を動かせるようにするか?
- 継盤のような動作をする
- 本筋は破壊しない
- コントローラーやスライダーで手数を動かすと本筋の前後に戻る
- 駒を動かす直前の局面に戻るべき? 要検討
# sp_board_cell_left_click_disabled
Type: Boolean
Default: false
盤上のセルをクリックしたときの通常処理を無効化するか? 要検討 この機能は sp_view_mode_piece_movable を false するのでいい気がしている。
# sp_location_click_behavior
Type: flip | nop
Default: flip
☗☖をクリックしたときの挙動
| 値 | 挙動 |
|---|---|
| flip | 視点を反転する |
| nop | 何もしない |
# sp_sfen_show
Type: Boolean
Default: false
盤面の下にSFENを表示するか? 削除予定
# sp_mounted_focus_to_slider
Type: Boolean
Default: false
起動時にスライダーがあればフォーカスするか?
- スライダーがなければ何もしない
- 再生モードで最初からスライダーにフォーカスしておけばそのまま左右ボタンで局面が切り替えることができて利用者に優しいUIになる
- スマホだととくにメリットはない
See also: sp_slider
# sp_operation_disabled
Type: Boolean
Default: false
全体の操作を無効化するか?
画像のような状態であってほしいときに使う。
# sp_piece_stand_blank_then_hidden
Type: Boolean
Default: false
持駒がないときは駒台を非表示にするか?
開戦していない局面を狭い領域にたくさん表示したいときだけ使う。
# sp_board_cell_class_fn
Type: Function
Default: null
盤面のセルのクラスを決める。
座標を引数にして呼び出すので例えば次のようにすると55の地点に「天王山」のクラスを付与する。
:sp_board_cell_class_fn="p => p.human_x === 5 && p.human_y === 5 && '天王山'"
Web Components 版では内部で eval しているため動作する。
# sp_double_click_threshold_ms
Type: Integer
Default: 350
編集モードで駒を反転するときのダブルクリックと認識する時間(ms)
ネイティブなダブルクリック判定を入れると通常のクリック判定が遅れるため自力判定している。
# sp_key_event_capture
Type: Boolean
Default: false
スライダーにフォーカスしていなくても左右キーで手数を動かせるようにするか? 非推奨
WARNING
副作用あり。他のプログラムの操作を奪ってしまうかもしれないため基本は false にしておいた方がよい。
# カメラ
- 見える範囲を指定する
- あくまで視野が変わるだけであって内部は符号座標9一を左上とした本将棋のままである
- 右上だけの表示でいいなら配列座標で左上を(4,0)でセル数を5x5などとする
- セル数を小さくすると壊れる
# sp_board_view_x
Type: Integer
Default: 0
左上(X)
# sp_board_view_y
Type: Integer
Default: 0
左上(Y)
# sp_board_view_w
Type: Integer
Default: 9
セル数(W)
# sp_board_view_h
Type: Integer
Default: 9
セル数(H)
# 合法手
# sp_legal_move_only
Type: Boolean
Default: true
操作モードで駒の移動を制限するか?
- false にすると?
- 禁じ手や手番の制約がなくなる
- ということは自分の手番で相手の駒を操作できる
- それを利用して後手のときも先手の駒を動かせばずっと先手側を操作できるので先手だけの囲いの手順の棋譜(SFENに限る)を作ったりするのが簡単になる
- SFENに限る理由は駒の種類を見ていないため
# sp_piece_auto_promote
Type: Boolean
Default: true
操作モードで死に駒になるときは自動的に成るか?
- 有効にすると「桂」を「11」に飛んだとき自動的に成る
- 完全なリアル対局をイメージしたいときは
falseにする
# sp_my_piece_only_move
Type: Boolean
Default: true
操作モードで動かせるのは自分の駒だけとするか? 要検討
sp_human_sideと機能が重複しているような気がする
# sp_my_piece_kill_disabled
Type: Boolean
Default: true
操作モードでは味方の駒を取れないようにするか?
# 詰み
# sp_request_checkmate_stat
Type: Boolean
Default: false
操作モードで詰み判定するか?
- 体感できるほどではないが、わりと重い処理のためデフォルトでは無効としている
<!DOCTYPE html>
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<script defer src="https://cdn.jsdelivr.net/npm/shogi-player@2.0.0"></script>
<script type="module">
const el = document.querySelector("shogi-player-wc")
el.addEventListener("ev_play_mode_move", e => {
const params = e.detail[0]
alert(params.checkmate_stat.yes_or_no === "yes" ? "詰み" : "詰み逃し")
})
</script>
</head>
<body>
<shogi-player-wc
sp_mode="play"
sp_body="position sfen 6+Rgk/6Ggl/8P/5B2+R/6N2/9/9/9/9 b Nb4s2n3l17p 1"
></shogi-player-wc>
</body>
</html>
See also: ev_play_mode_move
# 反則
# sp_illegal_validate
Type: Boolean
Default: true
操作モードで反則の判定をするか?
| 反則名 | 反則ブロック対応 | 備考 |
|---|---|---|
| 二歩 | ○ | |
| 打ち歩詰め | ○ | |
| 駒ワープ | ○ | |
| 死に駒 | ○ | |
| 王手放置 | ○ | |
| 王手解除せず | ○ | |
| 自殺手 | ○ | |
| ピン外し自殺手 | ○ | |
| 千日手 | × | 厳密には反則ではなく引き分け |
| 連続王手の千日手 | × |
- 反則ブロック対応とは
sp_illegal_cancelを有効にしたときのこと - 千日手系は設計ミスにより指す前に判定ができないので将来的にはなんとかしたい TODO
<!DOCTYPE html>
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<script defer src="https://cdn.jsdelivr.net/npm/shogi-player@2.0.0"></script>
<script type="module">
const el = document.querySelector("shogi-player-wc")
el.addEventListener("ev_play_mode_move", e => {
const params = e.detail[0]
if (params.illegal_hv_list.length > 0) {
const names = params.illegal_hv_list.map(e => e.illegal_info.name).join(",")
alert(names)
}
})
</script>
</head>
<body>
<shogi-player-wc
sp_mode="play"
sp_body="position sfen 7k1/5Gb2/7SL/8K/6s1P/9/9/9/8L b GNP 1"
></shogi-player-wc>
</body>
</html>
See also: ev_play_mode_move
# sp_illegal_cancel
Type: Boolean
Default: false
反則検知にひっかかったあと反則を無かったことにするか?
- 無かったことにしてもイベントで反則を知ることはできる
- 有効にすると基本的な反則の操作はできなくなる
- 有効にすると将棋ウォーズのようになる
- 千日手関連は判定できない
# 千日手関連
# sp_request_position_hash
Type: Boolean
Default: false
操作モードのイベント ev_play_mode_move に現局面のハッシュを含めるか?
See also: ev_play_mode_move
# sp_request_op_king_check
Type: Boolean
Default: false
操作モードのイベント ev_play_mode_move に相手に王手しているかどうかの結果を含めるか?
- アプリ側で初心者向けに「王手!」などと表示することができる
- 連続王手の千日手を判定するには
sp_request_position_hashと合わせて有効にする
<!DOCTYPE html>
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<script defer src="https://cdn.jsdelivr.net/npm/shogi-player@2.0.0"></script>
<script type="module">
const el = document.querySelector("shogi-player-wc")
el.addEventListener("ev_play_mode_move", e => {
const params = e.detail[0]
if (params.op_king_check) {
alert(params.op_king_check ? "王手" : "王手していない")
}
})
</script>
</head>
<body>
<shogi-player-wc
sp_mode="play"
sp_body="position sfen 8k/9/6+R2/9/9/9/9/9/9 b r2b4g4s4n4l18p 1"
sp_request_op_king_check="true"
></shogi-player-wc>
</body>
</html>
See also: ev_play_mode_move
# Web Components 専用
# sp_pass_style
Type: String Hash
Default: null
style 属性の代替
shogi-player-wc::part(root) {}を使わず直接タグにCSS変数を渡したいときに使う- Web Components では style を指定しても内側(Shadow Dom)には届かないため引数を設けている
- また Web Components 経由ではネイテイブなハッシュは渡せないのでJSON5形式文字列で指定する
- 最終的に ShogiPlayer.vue コンポーネントの style に渡す
<shogi-player-wc
sp_pass_style="{'--sp_board_color': 'LightSkyBlue'}"
></shogi-player-wc>
# sp_pass_css
Type: String
Default: null
Shadow DOM 内に指定のCSSを渡す。 自己責任
- Shadow DOM 内でCSSは隔離される。これは Web Components が他のWebページやWebアプリとの完全な分離を保証するために必要な機能である。だがWeb開発者にとっては制約となる場合もある。その制約を回避する禁じ手がこれ。
- ShogiPlayer.vue コンポーネントの内側で style タグを生成してそのコンテンツとする
例えばこれで盤のスタイルを自由に変えられるが後に BoardTexture の名前は変わるかもしれない。
<shogi-player-wc
sp_pass_css=".BoardTexture { background-color: LightSkyBlue }"
></shogi-player-wc>
# 盤と特定のセルに着色し、盤駒に影をつける例
<!DOCTYPE html>
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<script defer src="https://cdn.jsdelivr.net/npm/shogi-player@2.0.0"></script>
</head>
<body>
<shogi-player-wc
sp_pass_css="
:host {
--sp_board_color: LightSkyBlue;
}
.place_7_6, .place_2_6 {
background-color: LightPink;
}
.BoardTexture, .PieceObject {
filter: drop-shadow(4px 4px 4px oklch(from black l c h / 0.5));
}
"
></shogi-player-wc>
</body>
</html>
# sp-pass-props
Type: String
Default: null
v-bind 属性の代替
- Web Components + Vue 3 専用
- Vue.js 2 で作成した Web Components を Vue 3 と組み合わせたとき
snake_caseなパラメータ名を持つ値が渡せない問題がある - いまのところ、これを回避する方法がないため代替パラメータを用意した
- ここだけ例外的に
kebab-caseで書かないといけない - JSON5 形式の文字列としてパースする
- 型変換は JSON5 のパーサーに任せている
- Boolean 型は
"true"ではなくtrueと書く - Hash も Hash 型としてそのまま記述する
- 文字列として書いてもよいがエスケープがものすごく大変になる
- Boolean 型は
- JSON5 なのでコメントも書ける
<shogi-player-wc
sp-pass-props="{
sp_body: 'position sfen lnsgkgsnl/1r7/ppppppppp/9/9/9/PPPPPPPPP/1B5R1/LNSGKGSNL w - 1 moves 7a6b 7g7f 5c5d 2g2f',
sp_controller: true,
// CSS変数を渡す場合 ← コメント可
sp_pass_style: {
'--sp_board_color': 'blue',
},
}"
></shogi-player-wc>
# Development
# sp_dev_tools
Type: Boolean
Default: false
開発ツールを起動するか?
# sp_dev_tools_position
Type: left | right | top | bottom
Default: left
開発ツールの画面位置
# sp_dev_tools_group
Type: main | style | event | sfen | debug | props | data | cog
Default: main
開発ツールのタブ
# sp_device
Type: touch | desktop
Default: null
デバイスを強制的に指定する。
- 自動判別するので基本そのままでよい
- デバイス判別によって駒を動かすときの挙動が変わる
| 値 | 意味 | 挙動 |
|---|---|---|
| touch | タッチパネル操作 | 持ち上げた駒がマウスポインタについてこないかわりに移動元の色で駒を持ち上げたのがわかるようにする |
| desktop | マウス操作 | 持ち上げた駒がマウスポインタについてくる |
# sp_layer
Type: Boolean
Default: false
レイヤーを確認するか?
# sp_debug
Type: Boolean
Default: false
デバッグモードを有効にするか?
# sp_event_log
Type: Boolean
Default: false
イベント情報を JavaScript コンソールに出力するか?
# Slot
# sfen_part
引数: sfen, xcontainer
sp_sfen_show のときに表示する sfen の部分 非推奨