UCI Options

Some GUIs now support UCI options. For example, in the Shark GUI (鲨鱼界面) on PC (free Shark version 1.7.9 or later, commercial Shark version 2.3.1 or later), click the 🔧 wrench icon in the engine bar (next to the thread and hash settings) to open the engine option settings, as shown below:

For example, where to set engine UCI options in the Shark GUI

Descriptions of some Pikafish options

Sixty Move Rule

Toggle · Default: on

The switch for the 60-move rule, on by default. By default, for example, the engine takes into account that 60 full moves (120 plies) without a capture is a draw, and treats a position after 60 full moves without a capture as a score of 0.

If you want to analyze a position without the 60-move rule, don't like the 60-move rule being factored into the engine's calculation, or your platform or GUI is not compatible with Pikafish's 60-move rule, you can turn this setting off. If you notice inexplicable piece-sacrificing moves, this option is very likely the cause, which means the rule is incompatible with the 60-move rule of the platform or GUI you are playing on, and you can turn it off. (Actually, sacrificing pieces is not a real problem: once 60 full moves without a capture are reached, the engine already scores the position as 0, so any move that doesn't immediately lead to a capture scores 0.)

Pikafish's 60-move rule does not count a side's checking moves beyond 10 checks toward the move limit, and the corresponding replies to check are not counted either; but once a capture occurs in the position, the check count is reset.

Rule60MaxPly

Default: 120 · Range: 1 ~ 150

This option takes effect only when "Sixty Move Rule" is on. It sets the number of plies for the 60-move rule, with a range of 1 to 150 and a default of 120; 120 is the move-limit rule used by Tiantian Xiangqi (天天象棋). Note that 120 plies is 60 full moves.

For example, with 120, the engine takes into account that 60 full moves (120 plies) without a capture is a draw, and treats a position after 60 full moves without a capture as a score of 0.

Note

Except for special cases when analyzing a position, changing this option is not recommended, because the engine's search parameters are coupled to the 120-ply limit. If you set it much lower, playing strength may end up worse than simply turning the rule off. Also, once the engine reaches the ply count it believes is the limit, its subsequent moves become random. It is only suitable for special analysis cases, for example a position with a big advantage where you want to find a possible quick simplification or capture line. Remember to set it back to 120 afterwards; otherwise you may get absurd results in future analysis or engine league testing.

Clear Hash

Clears the engine's current hash memory. The most common way to get the same effect, though, is simply to reload the engine.

MultiPV

Default: 1 · Range: 1 ~ 500

Multiple principal variations. By default the engine shows 1 principal variation when analyzing a position. When you change this option, the engine increases the number of principal variations for the current position during analysis. All the variations are searched to the same depth and shown at the same time (that is, multiple lines are displayed for the same depth).

Put another way, it makes more moves get the "principal variation treatment" in the calculation, whereas by default only one move gets it.

The range is 1 to 500, and the default is 1, meaning a single principal variation.

Note

Increasing the number will reduce playing strength. It is for analysis only, and please do not use it in real games or engine testing. It also only increases the number of principal variations for the current position; subsequent positions are searched as usual (obviously, otherwise the search would explode exponentially).

Note: PV stands for Principal Variation.

Skill Level

Default: 20 (no strength limit) · Range: 0 ~ 20

Limits the engine's playing strength. When set to anything other than 20, the engine has some probability of choosing a weaker variation when it plays (and MultiPV = 4 is turned on at the same time), which can be used for human-vs-engine games. Note that only the engine's chosen move is weakened; engine analysis is the same as with MultiPV = 4.

The range is 0 to 20, and the default of 20 means no strength limit.

However, if UCI_LimitStrength is turned on, Skill Level has no effect.

UCI_LimitStrength

Default: off

Off by default. Turning it on makes Skill Level ineffective and makes UCI_Elo take effect.

UCI_Elo

Range: 1280 ~ 3133

A finer way to limit the engine's playing strength, using the same handicapping principle as Skill Level. It takes effect only when UCI_LimitStrength is turned on. The range is 1280 to 3133; the lower, the weaker. If the 21 levels of Skill Level are not granular enough and you want a finer division of engine strength, use UCI_Elo. It limits strength in the same way as Skill Level, only more finely. Elo = 1280 equals 0 in Skill Level, the maximum 3133 equals 19, 2850 = 13, 2568 = 10, 2268 = 7, and 1777 = 4.

The values of UCI_Elo have been calibrated against the Xiangqi engine league rating list.

Mate Threat Depth

Range: 0 ~ 10

The number of full moves used to judge a "mate threat" (杀) under the Chinese rules. This option takes effect only when Repetition Rule is set to ChineseRule. The range is 0 to 10; with 0, the engine does not judge the so-called "mate threat" of the Chinese rules. With 1 to 10, the engine judges during search whether a repeating move is a mate threat within 1 to 10 full moves, and under the Chinese rules a mate threat may make a repetition a violation. The higher the value, the more playing strength drops. It is suitable for humans analyzing games under the Chinese rules.

Note: the so-called "Chinese rules" are formally the Xiangqi Competition Rules (象棋竞赛规则) published by the Chinese Xiangqi Association.

Repetition Rule

Possible values: AsianRule, SkyRule, ComputerRule, ChineseRule, AllowChase, YitianRule, NoJudgement

• AsianRule is the Asian rules (the version of the Asian rules as understood by the authors' team). The severity of violations is: perpetual check > perpetual chase of the same piece > others. It is 2-fold (a ruling is made as soon as a position repeats, that is, when it occurs for the 2nd time). Most online rules are Asian rules.

  Note: the so-called "Asian rules" are formally the World Xiangqi Rules published by the World Xiangqi Federation.

• SkyRule is the rule used by certain online platforms. Note that some online rules are slightly modified Asian rules, not the Chinese rules. It is used for post-game analysis of games played online, so that humans can better adapt to the platform's rules. Please judge for yourself whether an online rule is the Asian rules. (The author of this rule's code is skystarspython.)

• ComputerRule is based on the Chinese Chess Program Competition Rules (中国象棋程序竞赛规则) written by Pikafish's author. It differs slightly from AsianRule, and also differs considerably from all online platform rules, but it is the only rule whose rulings fully match all of the Asian rules' illustrated cases. It follows the written definitions of the Asian rules more strictly and is 3-fold (a ruling is made when a position occurs for the 3rd time).

• ChineseRule is a greatly simplified version of the Chinese rules, but is essentially a modified Asian rules. Note that no online platform currently uses the Chinese rules; at most they use slightly modified Asian rules. The Chinese rules are currently defined too vaguely and too intricately: complex cases depend heavily on the referee's subjective judgment, and every referee understands them differently, so there are essentially countless versions of the Chinese rules and it is absolutely impossible to program them.

  Pikafish's simplified Chinese rules rank violations by severity as: perpetual check > perpetual chase, perpetual mate threat, mate-threat/check cycles, check/chase cycles, mate-threat/chase cycles > others. With this option selected, the engine judges "mate threats" only when Mate Threat Depth is not 0.

• AllowChase forbids only perpetual check and allows every other repeating move. Because Xiangqi rules are not unified, in positions with a winning advantage you can analyze under this rule to find lines that don't involve repetition rules, avoiding possible repetition-rule problems.

• YitianRule is suitable for use on the Yitian (弈天) platform. Note, however, that the Yitian platform's 60-move-rule draw must be claimed manually by clicking.

• NoJudgement allows all repetitions, with no violation rulings at all.

Note

Remember to adjust the rules above whenever needed. For example, after analyzing with another rule, if you then run engine league tests, switch back to AsianRule; otherwise you may get absurd test results.

ScoreType

Possible values: Elo, PawnValueNormalized, Raw

The kind of score the engine displays. It does not affect playing strength.

• Elo: win-rate score. The raw score converted according to a win-rate model. Pikafish's Elo score (since 2024) is tied to Elo difference: 200 points means a 76% win rate in fast self-play games (the win rate commonly used in Xiangqi circles, that is, wins plus half of draws; for example 4 wins, 4 draws and 2 losses is a 60% win rate, and 3 wins, 4 draws and 3 losses is a 50% win rate). The relationship between Elo difference and win rate is shown in the charts below.
• PawnValueNormalized: the raw score divided by a constant for the value of a pawn.
• Raw: the raw score.

Curve of "win rate (wins + half of draws)" versus Elo score

Approximate curve of "winning probability (wins only)" versus Elo score

LU_Output

Default: on

On by default. When on, lowerbound and upperbound information is shown. In plain terms, the same depth may output results several times, for example when a depth is still being searched, incomplete search details are output. When off, each depth outputs only once.

This option only affects output, not playing strength.

DrawRule

Default: None

Possible values: None, DrawAsBlackWin, DrawAsRedWin, DrawRepAsBlackWin, DrawRepAsRedWin

• None is normal and is the default.
• DrawAsBlackWin means a draw counts as a Black win: the engine treats both repetition draws and 60-move-rule draws as Black wins.
• DrawAsRedWin means a draw counts as a Red win.
• DrawRepAsBlackWin means a repetition draw counts as a Black win: the engine treats only repetition draws as Black wins. When analyzing, you can use it if you don't want the engine to steer into a repetition draw in the short term.
• DrawRepAsRedWin means a repetition draw counts as a Red win.

The Pikafish engine does not guarantee playing strength under these rules, and especially the score evaluation is very unreliable; only the moves may be of some reference value.

If you change the rules above, remember to change them back when needed. For example, after analyzing with "draw counts as Black win", if you then run engine league tests, switch back to None; otherwise you will get absurd test results.

EvalFile

The name and path of the NNUE weights file the engine should load. By default the engine reads the file named pikafish.nnue in the same directory. You can rename the NNUE file and still have it loaded through this option. Most people don't need this; on phones, Youbu (优步) can use this option to configure multiple engines.

Some GUIs (especially homemade ones, such as the T GUI) do not switch the working directory to the engine's directory when loading an engine, so the engine cannot find the NNUE file. You can set the full path of the NNUE file through this option to fix the problem, or simply put pikafish.nnue in the GUI's directory (worth trying if the engine has no option-setting feature).

NumaPolicy

Default: auto

The default is auto, and you generally don't need to touch this option.

However, on Windows systems from 2022 and earlier, on multi-core servers, be aware that auto may fail to use all threads. You can change it to hardware or turn off hyper-threading. The former has allocation problems when running multiple engines; the latter may work normally.

Other options

The remaining options are basically not needed by most people (for example Threads and Hash, for which the GUI provides settings), and you can ignore them. If you want to know more, see the Wiki in the official Pikafish GitHub.