Star Gambit Computer Player SDK
doc fixes
Paul Johnecheck
(Jun 7, 2026, 1:35 PM EDT)
e474baed
10f112c6
+18
-32
+18
-32
README.md
+18
-32
README.md
···
1
-
# star Gambit SDK
1
+
# Star Gambit SDK
2
2
3
3
The Star Gambit SDK allows developers to build computer players (coms) and make them available for players online.
4
4
To write a com, you need to write one function: "given the board, what do I
5
5
do?". The SDK handles the rest. Connect it to the server with an API token and your com can be played.
6
6
7
7
```rust
8
-
use sg_sdk::{Com, Game, run_as_com};
8
+
//! Usage: cargo run --example random_com -- --token <api_token>
9
9
use rand::seq::SliceRandom;
10
+
use sg_sdk::{operate_com, Com, Game};
10
11
11
12
struct RandomCom;
12
13
13
14
impl Com for RandomCom {
14
-
fn act(&mut self, game: &Game) -> Vec<String> {
15
-
// Play one uniformly random legal action; the runner calls us again
16
-
// until the turn ends.
17
-
game.legal_actions()
18
-
.choose(&mut rand::thread_rng())
19
-
.cloned()
20
-
.into_iter()
21
-
.collect()
22
-
}
15
+
fn act(&mut self, game: &Game) -> Vec<String> {
16
+
// Play one random legal action; the runner calls us again until the
17
+
// turn ends. (A com could instead return a whole turn at once.)
18
+
.choose(&mut rand::thread_rng())
19
+
.cloned()
20
+
.into_iter()
21
+
.collect()
22
+
}
23
23
}
24
24
25
25
fn main() {
26
-
// Play assigned games forever, authenticated with the com's API token.
27
-
run_as_com("http://localhost", "<api_token>", || RandomCom).unwrap();
26
+
if let Err(e) = operate_com("random_com", || RandomCom) {
27
+
eprintln!("fatal: {e}");
28
+
}
28
29
}
29
30
```
30
31
···
39
40
```
40
41
41
42
`act` is called when it's your turn, and again while the turn continues. Return
42
-
the action(s) to play, in order (each a single SGN action from
43
-
`game.legal_actions()`), and include `"END"` to end the turn. You can return
43
+
the action(s) to play in the correct order, ending with `"END"` to end the turn. You can return
44
44
one action per call or the whole turn at once. **Each action is validated
45
45
against the engine before it's sent; illegal actions are skipped and logged.** A
46
46
call that makes no progress (all-illegal or empty) is retried with the same
···
70
70
1. **Log in.** Open [play.stargamb.it](https://play.stargamb.it) and log in (or
71
71
create an account if you don't have one).
72
72
2. **Open the COMS screen.** Reach it either way:
73
-
- **Settings → Manage COMs**, or
73
+
- **Settings → User → Manage COMs**, or
74
74
- **PLAY → VS COM**, then **Manage COMs** in the COM picker dialog.
75
75
3. **Register a COM.** Press **REGISTER A COM** and pick a difficulty. A new COM
76
76
slot appears with a permanent handle (e.g. `⎇001-00000000`). You may register
77
77
up to three.
78
78
4. **Reveal and copy the token.** On the COM's card, press **Reveal** next to
79
79
*API Token* to show it, then **Copy token** (or select the revealed text).
80
-
Keep it secret — anyone with the token can play as your COM. Pass it to
80
+
Keep it secret: anyone with the token can play as your COM. Pass it to
81
81
`run_as_com` / the examples as `<api_token>`.
82
82
83
83
## Running a com
···
126
126
cargo run --release --example debug_game -- fire random # trace one game turn by turn
127
127
```
128
128
129
-
`tests/com_ladder.rs` enforces the ladder (the stronger com never loses).
130
-
131
-
## How it works
132
-
133
-
The runner holds `/ws/com` open; each `b_assign` carries a `game_id` and
134
-
per-game `game_token`, which it joins over `/ws`. Local state is rebuilt from
135
-
the server's `HISTORY` (board config + full SGN replayed through the `stellar`
136
-
engine). `legal_actions` enumerates candidate placements/moves/attacks and
137
-
keeps only those `engine.execute(...)` accepts, so it matches the server
138
-
exactly. Each turn it calls `act`, validates each returned action against the
139
-
engine, sends the legal ones (one message each, skipping the rest), and applies
140
-
them locally to stay in step; opponent actions and game-end claims are
141
-
applied/acked as they arrive, with a re-request of history on any drift. The
142
-
join/lobby/`YOU_ARE`/`RESULT` handshake and a 5-second keepalive ping are all
143
-
handled for you.
129
+
`tests/com_ladder.rs` enforces the ladder (the stronger com never loses).