Xiangqi notation FEN guide: how engines like Pikafish encode a position, how WXF moves such as C2=5 work, and how a to i coordinates differ, with examples.
Xiangqi notation comes in three working forms. FEN describes a whole position in one line of text, which is how engines such as Pikafish receive a board. WXF notation records moves the way players read them, as in C2=5. Coordinate notation gives every point a fixed name, so the same move becomes h2e2.
If you only want to follow printed games, our beginner guide How to Read Xiangqi Notation: A Simple Guide for Beginners covers the traditional system. This article is for the next step: saving positions, pasting them into analysis tools and converting between formats without mistakes. Every position string below has been checked against the rules engine that runs XiangqiPlay.
The starting position as a FEN string
FEN stands for Forsyth-Edwards Notation, a format borrowed from Western chess and adapted to the xiangqi board. Here is the starting position as engines write it:
rnbakabnr/9/1c5c1/p1p1p1p1p/9/9/P1P1P1P1P/1C5C1/9/RNBAKABNR w - - 0 1
This exact string is the start position built into the open-source engine Pikafish, and it is also the example given in the long-standing Chinese specification published on xqbase. It has six fields separated by spaces. The first and longest describes the pieces. The second says whose turn it is. The rest are housekeeping, which we come to below.
Reading the board field
The board is described one rank at a time, starting from the far side. The first group is Black's back rank, rank 9, and the last group is Red's back rank, rank 0, so you read the string as if you were sitting in Red's chair looking across the board. Ranks are separated by slashes, and because the board has ten ranks there are always nine slashes.
Within each rank you read from Red's left to Red's right, file a to file i. Pieces are single letters, uppercase for Red and lowercase for Black: K for the General, A for the Advisor, B for the Elephant, N for the Horse, R for the Chariot, C for the Cannon and P for the Soldier. B and N come straight from chess, where they stand for bishop and knight. A digit means that many empty points in a row.
Take the third group, 1c5c1. That is one empty point, a Black Cannon, five empty points, another Black Cannon and one more empty point, which puts Black's Cannons on files b and h. A quick sanity check for any FEN you type by hand: the letters and digits in every rank must add up to exactly nine points.
Side to move and the housekeeping fields
The second field is the side to move, w for Red and b for Black. The w is another chess leftover. Pikafish, which grew out of the chess engine Stockfish, still calls the two sides white and black internally and accepts only w or b here. The Chinese specification on xqbase also uses w, while noting that many xiangqi programs write r for Red instead. If you are preparing positions for an engine, use w.
The third and fourth fields exist in chess for castling rights and en passant captures. Xiangqi has neither, so both are always written as a single hyphen.
The fifth field counts half-moves since the last capture. The Chinese specification ties it to the sixty-move rule, under which 120 half-moves without a capture means a draw, and Pikafish refuses a FEN whose counter is above 119. The sixth field is the move number, which starts at 1 and goes up after each Black move. For a position you have set up to study, 0 and 1 are fine.
Letters you will meet instead
Not everyone agrees on the letters. The World Xiangqi Federation recommends E for the Elephant and H for the Horse in move notation, and English game records sometimes write S for the Soldier. If you type a FEN by hand it is easy to slip into those letters, and a strict engine will reject them. Some interfaces are more forgiving with move records: the xqbase specification describes one that reads either B or E as an Elephant and either H or N as a Horse. If a pasted position refuses to load, check the piece letters and the side-to-move letter before anything else.
Individual programs sometimes keep positions in formats of their own, such as a fixed string of 90 characters with one character per point. That works fine inside one application, but standard FEN is what you want when moving a position from one tool to another.
Worked example: two opening moves
Start from the initial position and play the most common opening: Red's Cannon to the centre, C2=5, and Black's Horse up to guard, H8+7. The FEN becomes:
rnbakab1r/9/1c4nc1/p1p1p1p1p/9/9/P1P1P1P1P/1C2C4/9/RNBAKABNR w - - 2 2
Compare it with the start. Black's back rank, rnbakab1r, now has a gap where the Horse on file h stood. The third group, 1c4nc1, shows the Horse arriving on file g, right beside the Cannon on h. Lower down, Red's Cannon rank has changed from 1C5C1 to 1C2C4, with the Cannon now on the central file e. It is Red's turn again, two half-moves have passed without a capture, and the game is on move 2.
Worked example: a mate in one
FEN is just as handy for small study positions. Try this one:
3k5/9/9/9/9/8R/9/9/9/4K4 w - - 0 1
Decode it rank by rank. The top group, 3k5, puts the Black General on d9, after three empty points. Four empty ranks follow. The group 8R places a Red Chariot on i4, at the right-hand edge. Three more empty ranks, and then 4K4 puts the Red General on e0, in the middle of its palace. Red is to move.
The winning move is R1=6 in WXF notation, the Chariot sliding across from file i to file d, which is i4d4 in engine coordinates. The Black General is now in check down the d-file. Stepping forward leaves it on the same file, and stepping sideways to e9 is illegal because the e-file is empty all the way down to the Red General and the two Generals may never face each other. The palace offers no other exits from d9, so it is checkmate, and it is the only mating move in the position. The FEN after the move is 3k5/9/9/9/9/3R5/9/9/9/4K4 b - - 1 1.
WXF move notation
WXF notation, named after the World Xiangqi Federation, is the English form of the traditional Chinese system. A move has four parts: the piece letter, the file the piece starts on, an operator and a final number. Files are counted from each player's own right, so Red's file 1 is Black's file 9. The operator is + for forward, - for backward and = for a sideways move along a rank, although some sources use a dot instead of the equals sign.
The final number means different things for different pieces. For pieces that move in straight lines, the Chariot, Cannon, Soldier and General, a sideways move gives the destination file and a forward or backward move gives the number of ranks travelled. Pieces that move diagonally, the Horse, Elephant and Advisor, always give the destination file. So C2=5 is a Cannon moving from file 2 across to file 5, H8+7 is a Horse jumping forward from file 8 to file 7, and C5+5 would be a Cannon advancing five ranks up the central file.
When two identical pieces stand on the same file, the file number is replaced by + for the front piece and - for the rear one. The Chinese 后炮平4, the rear Cannon moves across to file 4, becomes C-=4. Rarer situations, such as three Soldiers on one file, have conventions of their own, and sources do not all write them the same way.
Coordinates and the off-by-one trap
Coordinate notation ignores whose move it is. Every point has one fixed name: files a to i from Red's left, and ranks counted from Red's side of the board. Engines count the ranks from 0 to 9, which is the convention of the Chinese engine protocol UCCI and of Pikafish. In that system the two opening moves above are h2e2 and h9g7, and the mate is i4d4. A typical engine command looks like position startpos moves h2e2 h9g7, or position fen followed by a FEN string and the moves played since.
Many human-facing sites count ranks from 1 to 10 instead. XiangqiPlay's own move list works that way, showing the piece's character followed by the start and end points, so the central Cannon move appears as h3 to e3 and Black's reply as h10 to g8. The files match in both systems, and the rank is always one higher in the 1 to 10 style. Forgetting that difference is the most common reason a pasted move list suddenly produces illegal moves.
Which format to use
Use FEN whenever you need to save or share a position, with the standard letters, w or b for the side to move and nine slashes. Use WXF or the Chinese original for game records that people will read, because that is how books and broadcasts write moves. Use 0 to 9 coordinates for anything an engine will read, and remember the shift of one rank when you copy moves from a site that counts from 1 to 10.
The best way to make any notation stick is to use it on real positions. Try writing out the FEN of a puzzle from XiangqiPlay's library of 5,000 engine-proven mates before you solve it, or record the first moves from one of the site's opening guides in both WXF and coordinates. After a few sessions the strings start to read like a board.
XiangqiPlay Team
XiangqiPlay newsroom
