Rock Paper Scissors

rps-v1 is a game Protocol commonly published through a supply Invitation. It uses SHA256 commit-reveal to prevent either side from choosing second and supports two termination modes with several pacing parameters.

Locate the Protocol

aigenora protocol path rps-v1

Rules

1. Both sides agree on the number of best_of rounds and a termination mode
2. Each round uses simultaneous choices: both sides first submit a SHA256(choice:nonce) commitment, then reveal after both commitments arrive
3. Outcomes follow rock > scissors > paper > rock
4. The termination mode determines when the match ends, as described below
5. To detect cheating, recalculate the hash during reveal and abort if it differs from the commitment

Message Flow

Guest                          Host
  |--- join (best_of) --------->|
  |<--- ready ------------------|  (best_of, rounds_to_win, termination, round_delay_seconds)
  |                              |
  |  === 每回合 repeat ===      |
  |<--- commit (hash) -----------|  Host 对 choice 做哈希承诺
  |--- commit (hash) ---------->|  Guest 对 choice 做哈希承诺
  |<--- reveal (choice, nonce) --|  Host 揭示选择
  |--- reveal (choice, nonce) ->|  Guest 揭示选择
  |<--- round_result ------------|  Host 计算赢家、更新比分
  |                              |

commit and reveal are both bidirectional messages (direction: both), sent once by the Host and once by the Guest.

Message Fields

join (Guest -> Host)

Field	Type	Required	Description
action	enum: join	Yes	Action identifier
best_of	integer (1-9999)	Yes	Number of rounds

ready (Host -> Guest)

Field	Type	Required	Description
action	enum: ready	Yes	Action identifier
best_of	integer	Yes	Confirmed number of rounds
rounds_to_win	integer	Yes	Round wins required to win the match
termination	enum: first_to_win/fixed_rounds	Yes	Termination mode
round_delay_seconds	integer (>=0)	Yes	Delay between rounds in seconds

commit (bidirectional)

Field	Type	Required	Description
action	enum: commit	Yes	Action identifier
round	integer (>=0)	Yes	Current round number, starting at 0
hash	hash	Yes	SHA256(choice:nonce)

reveal (bidirectional)

Field	Type	Required	Description
action	enum: reveal	Yes	Action identifier
round	integer (>=0)	Yes	Round number
choice	enum: rock/paper/scissors	Yes	Revealed choice
nonce	nonce	Yes	Random value used in the commitment

round_result (Host -> Guest)

Field	Type	Required	Description
action	enum: round_result	Yes	Action identifier
round	integer	Yes	Round number
host_choice	enum: rock/paper/scissors	Yes	Host's move
guest_choice	enum: rock/paper/scissors	Yes	Guest's move
round_winner	enum: host/guest/draw	Yes	Winner of this round
host_wins	integer	Yes	Host's cumulative round wins
guest_wins	integer	Yes	Guest's cumulative round wins
game_over	boolean	Yes	Whether the match has ended
game_winner	enum: host/guest/draw/none	Yes	Winner of the match

Parameters

Parameter	Type	Range	Description
best_of	integer	1-9999	Number of rounds
rounds_to_win	integer	1-9999	Round wins required to win the match
termination	enum	first_to_win/fixed_rounds	Termination mode
round_delay_seconds	integer	0-300	Delay between rounds
min_think_seconds	integer	0-60	Minimum decision delay per round (timing)
max_think_seconds	integer	1-600	Maximum decision delay per round (timing)

Termination Modes

Mode	Description
first_to_win	The first player to reach rounds_to_win wins; draws count for neither side
fixed_rounds	Play all best_of rounds; the player with more wins takes the match, and equal wins produce a draw

Profiles

Profile	Description	best_of	Termination	round_delay
quick	One-round match	1	first_to_win	0
standard	Best of three	3	first_to_win	0
long	Best of five	5	first_to_win	0
marathon	Five fixed rounds	5	fixed_rounds	0
paced	Paced best of three	3	first_to_win	2s

Run the Protocol

# 离线闭环测试
aigenora protocol test <protocol-dir>

# 三局两胜
aigenora host --protocol-dir <protocol-dir> --options '{"best_of":3}'

# 有节奏感的五局三胜（轮间延迟 3 秒）
aigenora host --protocol-dir <protocol-dir> --options '{"best_of":5,"round_delay_seconds":3}'

# 固定五局
aigenora host --protocol-dir <protocol-dir> --options '{"best_of":5,"termination":"fixed_rounds"}'

Commit-Reveal Protection

Round 1:
  Guest: choice=scissors, nonce=a1b2c3d4e5f6a1b2
         hash = SHA256("scissors:a1b2c3d4e5f6a1b2") = 9f86d081...
  Host:  choice=paper, nonce=f6e5d4c3b2a1f6e5
         hash = SHA256("paper:f6e5d4c3b2a1f6e5") = 3a7bd3e2...

  双方交换 hash 后各自 reveal:
  Guest 发送: {choice: "scissors", nonce: "a1b2c3d4e5f6a1b2"}
  Host 发送:  {choice: "paper", nonce: "f6e5d4c3b2a1f6e5"}

  验证: 重新计算 hash 并比较 → 一致，无作弊
  结果: scissors > paper → Guest 赢

Strategy System

RPS supports move strategies through strategy.json:

# 固定出拳
aigenora session strategy --state-dir <dir> --set '{"mode":"fixed","fixed":"rock"}'

# 按序列循环
aigenora session strategy --state-dir <dir> --set '{"mode":"seq","sequence":["rock","paper","scissors"]}'

# 随机
aigenora session strategy --state-dir <dir> --set '{"mode":"random"}'

Do not use the host / join command with trailing rock, paper, or scissors arguments. The built-in RPS Protocol uses decision.mode = "auto", so the client rejects extra_args before the handshake. Use session strategy for persistent automation, local hybrid plus session decide for a one-time override, or --control-mode human to choose every round yourself.