盤面管理（Board / PositionState）

rsshogi.core.Board は将棋の盤面状態、指し手の適用と取り消し、合法手生成、対局状態の判定を担う中核クラスである。 また、盤面の個別マスや持ち駒を直接編集する用途向けに、構造化データクラス PositionState と妥当性検証クラス ValidationReport、ValidationIssue を提供する。

from rsshogi.core import (
    Board,
    PositionState,
    ValidationIssue,
    ValidationReport,
)

クラス一覧と例外ポリシー

Board および PositionState のメソッドは以下の例外ポリシーに従う。

• 型エラー（TypeError）：引数の型がシグネチャと一致しない場合に送出する。
• 値エラー（ValueError）：不正な SFEN 文字列、非合法手、表現範囲外の数値、盤面上で解決できない指し手などを渡した場合に送出する。
• 未存在の表現（None）：last_move() や pop() で着手履歴が空の場合、または solve_mate_in_one() で 1 手詰めが存在しない場合は例外を送出せず None を返す。

メソッドとプロパティの早見表

局面の初期化と入出力

Board(sfen: str | None = None) -> Board

sfen に None を渡すと平手初期局面で初期化する。 任意の初期局面から開始する場合は SFEN 文字列を指定する。

Note

Board() は引数省略時に平手初期局面になるが、後述する PositionState() は引数省略時に駒が置かれていない空盤面（"9/9/9/9/9/9/9/9/9 b - 1"）になる。

set_usi_position(position) は以下の形式を受理し、moves 以降の手順を合法手として順番に適用する。

• "startpos" または "position startpos"
• "sfen <board> <turn> <hand> <ply>" または "position sfen <board> <turn> <hand> <ply>"
• 上記に "moves <usi1> <usi2> ..." を続けた文字列

from rsshogi.core import Board

board = Board()
board.set_usi_position("position startpos moves 7g7f 3c3d")
print(board.to_sfen())
# => "lnsgkgsnl/1r5b1/pppppp1pp/6p2/9/2P6/PP1PPPPPP/1B5R1/LNSGKGSNL b - 3"

clone = board.copy()
print(board.to_csa())
print(board.to_bod())

局面の妥当性検証

set_position_state() などで構築した盤面が将棋のルール上妥当な配置を満たしているかを検証する。

バイナリシリアライズと Apery 互換変換

学習データや教師局面ファイルの入出力向けに、YaneuraOu 系の PackedSfen / PackedSfenValue（PSV）および Apery / cshogi 系の HuffmanCodedPos（HCP）/ HuffmanCodedPosAndEval（HCPE）への直接変換を提供する。 NumPy の構造化配列との連携手順は NumPy 連携 を参照。

出力先バッファ out と入力引数の仕様

• out バッファの受け入れ型：
  • to_packed_sfen / to_hcp：書き込み可能な長さ 32 の bytearray や uint8 1 次元 ndarray、または要素数 1 の PackedSfen / HuffmanCodedPos 構造化 ndarray（shape (1,) または 0 次元スライス arr[i]）。
  • to_psv：書き込み可能な長さ 40 の bytearray や uint8 1 次元 ndarray、または PackedSfenValue 構造化 ndarray（shape (1,) または 0 次元スライス arr[i]）。
  • to_hcpe：書き込み可能な長さ 38 の bytearray や uint8 1 次元 ndarray、または HuffmanCodedPosAndEval 構造化 ndarray（shape (1,) または 0 次元スライス arr[i]）。
• set_packed_sfen / set_hcp の入力型：
  • 長さ 32 の bytes、bytearray、Sequence[int]、uint8 1 次元 ndarray、または要素数 1 の構造化 ndarray（shape (1,) または 0 次元スライス arr[i]）を受理する。
• to_psv の引数：
  • mv：Move、Move32、int（0..=65535）、USI 文字列、または None（省略時は Move.NONE）。
  • score：int（int16 範囲のセンチポーン評価値、既定値 0）。
  • game_result：GameResult、int、結果名文字列、または None（省略時は GameResult.INVALID）。
  • game_ply：int | None（uint16 範囲の手数、省略時は board.game_ply）。
• to_hcpe の引数：
  • best_move：AperyMove、AperyMove32、Move、Move32、int（0..=65535 の AperyMove 値）、USI 文字列、または None（省略時は AperyMove(0)）。渡された指し手は盤面参照なしで 16 ビットの AperyMove に直接変換される。
  • score：int（int16 範囲のセンチポーン評価値、既定値 0）。
  • game_result：必須引数（None は ValueError）。GameResult（引き分け系、先手勝ち系、後手勝ち系の各定数）、文字列（"DRAW"、"BLACK_WIN"、"WHITE_WIN"、大文字小文字不問）、または HCPE 数値コード（0：引き分け、1：先手勝ち、2：後手勝ち）を指定する。

Warning

片玉、玉なし、または標準枚数を超える駒を含む局面は PackedSfen および HuffmanCodedPos では表現できず、変換時に ValueError を送出する。

import numpy as np
from rsshogi.core import Board
from rsshogi.numpy import HuffmanCodedPosAndEval, PackedSfenValue
from rsshogi.record import GameResult

board = Board()

# PSV 配列への直接書き込み（0 次元スライスへの書き込みにも対応）
psv_arr = np.zeros(2, dtype=PackedSfenValue)
board.to_psv(mv="7g7f", score=50, game_result=GameResult.BLACK_WIN, out=psv_arr[0])

# HCPE 配列への直接書き込み
hcpe_arr = np.zeros(1, dtype=HuffmanCodedPosAndEval)
board.to_hcpe(best_move="7g7f", score=50, game_result="BLACK_WIN", out=hcpe_arr)

指し手の適用と取り消し

盤面に対して指し手を適用して手を進めるメソッドと、直前の手を取り消して戻すメソッドを提供する。

push_usi_with_delta(usi) の戻り値スキーマ

push_usi_with_delta(usi) が返す辞書は、すべての手で共通のキーと、kind（"BOARD" または "DROP"）に応じた固有キーを持つ。

from rsshogi.core import Board

board = Board()
delta = board.push_usi_with_delta("7g7f")
assert delta["kind"] == "BOARD"
assert delta["captured"] is None

popped = board.pop()
assert popped is not None and popped.to_usi() == "7g7f"

盤上の駒、持ち駒、ビットボードの参照

盤上のマスごとの駒配置、手番ごとの持ち駒、および条件別のビットボードを取得する。

from rsshogi.core import Board
from rsshogi.types import Color, PieceType, Square

board = Board()
print(board.piece_on(Square.from_usi("7g")))  # => P
print(board.king_square(Color.BLACK).to_usi())  # => "5i"
print(board.pieces_for(PieceType.PAWN, Color.BLACK).count())  # => 9
print(board.hand_counts(Color.BLACK))  # => {'P': 0, 'L': 0, 'N': 0, 'S': 0, 'B': 0, 'R': 0, 'G': 0}

利きと攻撃の判定

特定のマスに対する攻撃駒（アタッカー）の列挙や、特定の手番と駒種による利き範囲の計算を行う。

from rsshogi.core import Board
from rsshogi.types import Color, PieceType, Square

board = Board()
board.apply_usi("7g7f")

target = Square.from_usi("7e")
print(board.is_attacked_by(target, Color.BLACK))  # => True
print(board.attacks_by(Color.BLACK, PieceType.BISHOP).contains(Square.from_usi("3c")))  # => True

合法手と擬似合法手の生成および判定

from rsshogi.core import Board, Move

board = Board()
moves = board.legal_moves()
print(len(moves))  # => 30

candidate = Move.from_usi("7g7f")
if board.is_legal_move(candidate):
    board.apply_move(candidate)

対局状態、入玉宣言、1 手詰めの判定

手番、手数、Zobrist ハッシュ、王手、詰み、千日手、入玉宣言勝ち、1 手詰めの各判定を行う。

evaluate_declaration() の戻り値スキーマ

evaluate_declaration() が返す辞書は、共通キーと detail_type に応じた詳細キーを持つ。

from rsshogi.core import Board

board = Board()
info = board.evaluate_declaration()
print(info["rule"], info["can_declare"], info["points"], info["required_points"])
# => Point27 False 27 28

PositionState と妥当性検証クラス

PositionState

PositionState(sfen: str | None = None) -> PositionState
PositionState.from_sfen(sfen: str) -> PositionState

PositionState は盤上 81 マス、先後の持ち駒、手番、手数を保持する構造化データクラスである。 sfen=None で生成した場合は、すべてのマスが空で持ち駒なしの空盤面（"9/9/9/9/9/9/9/9/9 b - 1"、side_to_move=Color.BLACK、ply=1）となる。

ValidationReport

validate_all() が返す ValidationReport は以下のメンバーを持つ。

ValidationIssue

ValidationIssue は検出された個別の問題を表し、以下のプロパティを持つ。

ValidationIssue.kind の取り得る値は以下の 6 種類である。

from rsshogi.core import Board, PositionState
from rsshogi.types import Color, Piece, PieceType, Square

state = PositionState()
state.set_piece(Square.from_usi("5i"), Piece.from_color_type(Color.BLACK, PieceType.KING))
state.set_piece(Square.from_usi("5a"), Piece.from_color_type(Color.WHITE, PieceType.KING))
state.set_piece(Square.from_usi("7g"), Piece.from_color_type(Color.BLACK, PieceType.PAWN))
state.set_piece(Square.from_usi("7f"), Piece.from_color_type(Color.BLACK, PieceType.PAWN))

report = state.validate_all()
assert not report.is_valid()
for issue in report.issues:
    print(issue.kind, issue.file_usi, issue.message)
# => DOUBLE_PAWN 7 Double pawn for Black on file 7

# 修正して Board に反映する
state.set_piece(Square.from_usi("7f"), Piece(0))
assert state.is_valid()
board = Board()
board.set_position_state(state)

関連項目

• 基本型（Square / Piece / Hand / Bitboard）
• 指し手クラス（Move / Move32 / AperyMove）
• SVG 出力
• NumPy 連携
• 棋譜管理（Record）