TNoodleをAPI的に使う

TNoodleとは、WCA公式大会で使用されるスクランブルプログラムです。通常はウェブブラウザでぽちぽち実行しますが、スクランブルだけ欲しいときとかにAPI的に使いたかったりします。そのやり方をまとめたので公開します。

本記事では、CentOS で動かしながら実験していますが、TNoodleはJavaで実装されているのでどのOSでも同じようなことができると思います。

---

---

ダウンロード・インストール

まず、ダウンロード・インストールします。 直接WCAから.jarを取ってきても良いし、GitHubからソースコードを取ってきて.jarへコンパイルしても良いです。 両方同じなので、どっちでも大丈夫です。

.jar をダウンロードする方法はTNoodleのページでワンクリックするだけなので省略しますが、GitHubからダウンロード・コンパイルするには以下のように実行します。 Javaのコンパイル環境と、Python 3が必要です。

2019-08-30 追記:
現在の最新バージョン 0.15.0 は Gradle でビルドするように変わっています。
そしてめちゃめちゃ依存あって簡単にビルドできなくなってる…
素直にリリースのjarを使うのが手っ取り早いです。ちなみに、公式大会では公式ビルドを用いないといけない決まりがあります。
追記ここまで

$ git clone https://github.com/cubing/tnoodle.git
$ ./tmt make dist -p wca

そうすると、wca/dist/TNoodle-WCA.jar が生成されます。

実行させてみる

実行させるには、.jar をダブルクリックするが、コマンドラインで以下のように命令します。

$ java -jar wca/dist/TNoodle-WCA.jar

通常は (WCA Delegate が公式大会で有効なスクランブルを生成するには)、この .jar を実行させた上で、ウェブブラウザで http://localhost:2014/ にアクセスして種目やラウンド数等を指定してスクランブルを生成しますが、ここでURLを直打ちすることでバージョンを出力したり、スクランブルのみを取得したりできます。

2019-08-30 追記:
いつの間にかこのへんにAPIの情報がまとまっていました。
https://github.com/thewca/tnoodle/blob/master/webscrambles/src/main/resources/tnoodle_resources/webapps/ROOT/wca/readme-tnoodle.md
追記ここまで

バージョン情報

バージョン情報を出力するには、http://localhost:2014/version.json にアクセスします。 以下、curl コマンドを使用した場合の結果を示していますが、ウェブブラウザのURL欄に入力した場合も同じ結果が得られます。

$ curl "http://localhost:2014/version.json"
{"current":{"name":"TNoodle-WCA-0.11.1","information":"https://www.worldcubeassociation.org/regulations/scrambles/","download":"https://www.worldcubeassociation.org/regulations/scrambles/tnoodle/TNoodle-WCA-0.11.1.jar"},"running_version":"TNoodle-WCA-0.11.1-1461398264","allowed":["TNoodle-WCA-0.11.1"],"history":["TNoodle-0.7.4","TNoodle-0.7.5","TNoodle-0.7.8","TNoodle-0.7.12","TNoodle-WCA-0.8.0","TNoodle-WCA-0.8.1","TNoodle-WCA-0.8.2","TNoodle-WCA-0.8.4","TNoodle-WCA-0.9.0","TNoodle-WCA-0.10.0","TNoodle-WCA-0.11.1"]}

バージョン TNoodle-WCA-0.11.1 は、2016年4月23日時点での最新バージョンです。

パズルリスト

http://localhost:2014/puzzles.json にアクセスすると、TNoodleが出力可能なパズル一覧を見ることができます。

$ curl "http://localhost:2014/puzzles/.json"
[{"shortName":"222","longName":"2x2x2"},{"shortName":"333","longName":"3x3x3"},{"shortName":"333fm","longName":"3x3x3 Fewest Moves"},{"shortName":"333ni","longName":"3x3x3 no inspection"},{"shortName":"444","longName":"4x4x4"},{"shortName":"444fast","longName":"4x4x4 (fast, unofficial)"},{"shortName":"444ni","longName":"4x4x4 no inspection"},{"shortName":"555","longName":"5x5x5"},{"shortName":"555ni","longName":"5x5x5 no inspection"},{"shortName":"666","longName":"6x6x6"},{"shortName":"777","longName":"7x7x7"},{"shortName":"clock","longName":"Clock"},{"shortName":"minx","longName":"Megaminx"},{"shortName":"pyram","longName":"Pyraminx"},{"shortName":"skewb","longName":"Skewb"},{"shortName":"sq1","longName":"Square-1"},{"shortName":"sq1fast","longName":"Square-1 (fast, unofficial)"}]

スクランブル

これが本題で一番やりたかったことです。スクランブルを得るには次のように、
http://localhost:2014/scramble/.json?##param##
にアクセスします。##param## はリクエストパラメータです (GETで試していますが、多分POSTでも大丈夫です)。 拡張子 .json は .txt でも大丈夫です。 以下の実行例では、.txt でサンプルを掲載していますが、.txt を .json に置き換えてもフォーマットが変わるだけで内容は同じです。

以下の例では、333 のスクランブルを 5個 出力しています。パズル名として受け付けてくれる単語は、少し上で書いたパズルリストに載っているものです。 毎回実行するたびに、スクランブルは変わります。

$ curl "http://localhost:2014/scramble/.txt?e=333*5"
D' B2 D2 R2 B2 L2 F2 D U' B' L2 R D R' B' R B' F2 D' U2
R D2 B' D F U' R2 U B2 U' F' R' U2 D2 B2 D2 L' F2 L
B2 R2 U' B2 L2 F2 L' B' F2 U R' U B' L2 D U B2 U'
B L2 F L' U R U' R' B' D' R U B2 D R2 U L2 F2 R2
B L' U2 D' R' B2 L' F2 B' R2 L U2 D' R2 B2 R2 B2 L2 D F2

シードを与えても、イベントのキー値を変えるとスクランブルは変わります。 シードとイベント名を結合したものを内部的なシードとしているからです。

$ curl "http://localhost:2014/scramble/.txt?seed=12345&event=333*5"
U2 R D2 R U' R L D' R' F B2 D R2 B2 U2 D' R2 U R2
B2 U2 L F R' B' D' L' D2 F' U D2 B2 R D2 L2 D2 R' F2
F' R2 D2 R2 B2 U' R2 F2 L' F2 D F2 L2 B' L2 B U2 F'
F2 R' F2 L' B R2 U D B U R B2 D B2 U' F2 D2 R2 D' R2
F' U2 L' F2 U2 B D B' L' D' F B2 D F2 U F2 R2 U2 F2 B2

以下は、333 と 444 と 555 をそれぞれ 5 個ずつ生成した例です。生成には少し時間がかかります。 シードは同じでも、イベントが増えるとスクランブルが変わっていることがわかります。

$ curl "http://localhost:2014/scramble/.txt?seed=12345&e1=333*5&e2=444*5&e3=555*5"
U F' R' B R2 L' U' D' F D' R2 B L2 F' U2 F2 L2 U2 F2
U B2 F2 U' B2 L2 D B2 F2 L' F D L U F U B' D' F2 L'
D2 R2 F D2 R2 D2 F R2 B R B2 D L R2 F2 D' B U' L' U2
U2 B2 D' B2 R2 F2 L2 R2 D2 F' D' F U2 L' B' L' B' D' L' U
B2 L2 F' R2 D2 L2 D2 F' U2 F R' U2 B' F D F2 R
R2 F2 D2 R2 B' D2 F' L2 B F2 R' B' D' L2 R2 D' L B2 R B Rw2 U L2 B' Uw2 F2 D' Rw2 B Uw2 D U2 B Rw F' B' R F Rw2 Fw Uw' R Fw' R Uw2 U2
R2 B2 D2 R U2 L2 D2 L F R U2 D' L U2 B U' F2 R2 D Uw2 F2 R' B Rw2 B2 Uw2 Rw2 F R B2 F2 R' Uw' U F' R2 Uw Rw' B' D Rw' D L'
D U2 L2 F2 D2 L2 U' R2 L' U2 L' D' U R D' B L2 U' F Fw2 R' L2 Fw2 L2 Uw2 U Fw2 U2 L' U' R' L Fw' D' B2 Rw2 Fw' Rw' F' Uw' D' L' B' U2
B' L' B2 R2 B2 U F R2 U' F' D2 B2 U2 R2 B' R2 U2 F L2 Uw2 L' Fw2 U' B2 Rw2 Fw2 D2 Fw2 L2 R D' Fw F' R2 U R2 Rw' D' B' Uw2 Rw U Fw
F2 R2 B2 D R2 D2 F2 R2 U' L2 D2 R F2 D' U' R F U R2 U' Uw2 Fw2 Rw2 F' D B2 D2 Fw2 Rw2 U L2 U' Rw' B' L R U' Rw' U B2 Fw' R' Uw Rw' U
R2 D' Bw' Uw2 D2 Fw' Dw' U' F' L Bw R' L' Fw L F2 Bw R2 F2 Lw' R' Dw' Bw2 D R' Dw' U2 B2 R' L B' U D2 L' R2 Dw Bw Fw2 Dw2 Uw2 U' Lw2 B Lw2 F' Bw2 L' Bw U Uw Rw2 Dw Bw R L' Rw Uw Rw Bw Fw
Lw B2 Lw2 L2 U2 Dw' F Dw2 Uw' R2 Uw Rw' B Rw U' F Uw F' U Uw D' L Bw' B2 Dw R' Rw' F' Fw' B2 U' D' Lw2 U2 B2 F' L Fw B2 Rw2 D Lw Fw' Uw2 U Bw2 Uw' Lw2 Bw R' U' Rw' Dw2 L2 Dw2 D' Bw' Uw2 U Dw'
Uw L R' Lw Uw2 D' F2 L2 Rw Bw U2 Uw Rw2 Lw2 Fw Bw' R2 U R2 Bw' U D Fw' Uw' B2 Fw Bw2 D' Fw2 Dw B2 Lw2 B Lw2 D2 Bw2 R2 U' D Rw2 F2 Fw' U B2 U' B' Uw2 U' L' R2 U' Dw' Bw2 F R B2 Dw' Lw2 U' Dw'
Dw2 F' Dw Bw B R Fw2 Uw D2 Rw' Bw Dw2 F2 Lw D R D2 F Rw Fw' Lw U' Lw L U' Uw' Rw2 Fw D' F2 Rw2 R' B Dw2 Uw2 L U2 B2 Dw2 Rw' Dw2 D2 R' Fw Rw2 R Lw' Dw Bw D R2 U2 R2 Dw2 F2 Uw Rw' F' Bw' U'
Fw2 L2 D' Bw2 L2 Fw2 Rw' F2 L' Rw2 Lw2 U2 Fw' D Uw F2 R' L' Lw Rw' Fw2 R L' B' L' D Fw Rw' R2 D R2 Uw2 L2 B D' Fw2 U2 Fw' D Rw B' U' Fw2 Bw2 L R D2 B Dw' U2 Lw Rw2 R2 B2 F Rw B L' Fw' Rw2

シードは数値じゃなくて、文字列でも大丈夫です。

$ curl "http://localhost:2014/scramble/.txt?seed=abcde&e1=333*5&e2=444*5&e3=555*5"
B U2 B2 F' R2 D2 L2 R2 B D R' F' R' B2 D2 L F2 D U' L'
L' R' F2 D2 L2 F2 D2 U2 F2 R U' F D U F' D2 R2 U2 L' F
F R' D F B' L U2 B' R D F2 L' B2 D2 F2 B2 L' D2 R2 L
B U F B' D2 B' L2 F' U R' B' D2 R2 D2 B R2 B R2 B R2
B2 L F2 R2 F2 R' B2 D F' U R2 F2 L R2 F2 D F2 D
R2 U' B2 D2 B2 D L2 D' L' B2 U' D L' F B2 L' D' L' U' Rw2 Fw2 D F U' F2 Rw2 Uw2 F Rw2 F' U' Rw B' U2 L' Fw2 Uw Rw2 Uw' Rw L' Uw' D' L
R2 F2 R2 L2 D2 F L2 F' D2 F D' L B2 R' D' L' B2 D2 B Uw2 Fw2 U' R2 U Rw2 Uw2 U B2 U' L B2 Fw L2 Fw F2 R2 Fw2 Rw D B2 Rw' Fw2 L2 D'
U D2 L2 B2 R2 B2 D B L2 D' F U2 L2 U' L U2 R' F' Fw2 U' L Fw2 L Fw2 D B2 U' F2 Rw2 D2 Fw' D' R2 U2 Fw2 F2 U' B2 Rw Uw Fw2 Rw
U2 B2 L2 F2 D2 R2 U' L2 B2 D' F' L B L D F' U' F L2 Fw2 Uw2 F' U Rw2 D' B' Rw2 B2 Rw2 R2 Fw2 L2 Rw' B2 L' B' R2 Uw' Rw R U' Fw' Uw' L
L' U' L B' L' D' L2 F' B R F2 B2 L2 U B2 D2 L2 U' D2 Fw2 L Uw2 D' L2 U L D' R Uw2 D Fw' B F' R' Uw2 F' Rw F' L U' Rw' Uw R2 F
Lw' F2 Uw D2 B' Bw R2 Uw' B U' Dw' R' Bw2 L2 D Lw Uw2 L Bw' Dw' R Bw B2 L F Lw L Uw' U2 L' Bw2 D' R L D' Rw Dw D Lw Fw R Bw' D' R' D2 Fw F2 Uw F2 Lw Fw' F2 Bw2 Lw2 Bw2 R Fw' B2 R2 Bw2
D L Fw' B' Bw2 Rw2 Bw Lw D B2 F D2 Rw2 B R2 F' B' Dw2 U2 Lw' Uw2 L' Uw2 F2 U Rw F Bw2 L D' Rw2 Lw' R' Dw' F2 Lw2 Fw2 Uw2 Lw2 L' D2 F' Lw' B' Lw' Bw' R Uw2 R2 Fw' Rw Fw' U' F2 Rw' F2 Bw Lw2 B Bw'
Fw2 F' L Bw2 Rw' F2 R' F' Rw Fw2 Uw2 Fw' Lw U' Rw' Lw' F Lw L D2 R U2 Uw D' Fw' D' Fw R Fw2 Dw2 U F' Rw Lw Fw2 F Rw D' B2 Lw D Lw F2 Uw2 Rw2 F2 Fw2 Rw' R L D' Bw' U' Lw' Bw2 B2 R F' R' Uw
Uw' D2 Fw F2 Lw U2 Dw' Fw2 Uw' Bw2 Lw2 F' Uw Lw2 L' B' F Rw2 Fw' Uw L2 Rw2 Dw' Fw' B2 Bw' Dw' F' Dw2 Fw L2 B' Lw Fw' Uw' Dw' Fw' B' R' D2 Lw Rw Fw' B2 Lw Fw2 Uw Fw2 Dw2 U D' F D' Lw2 Fw2 U2 B' Lw' Bw Fw2
D R' Rw' B' Bw Lw2 Bw' B2 U Uw Rw R2 Dw Uw2 Bw' Rw F Dw D2 Bw' L D R' B2 Fw R' Bw2 Rw Dw' L2 Dw Fw' B2 Bw' Dw2 R2 Uw' F B' U B Uw' B Uw Fw D2 Bw2 Fw' B' L' F Rw U' Lw2 R2 L' F2 Bw2 B Rw2

目隠しのスクランブルは内部的には “no inspection” というパズルの分類になります。スクランブルの後ろの方にキューブ自体を回転させるムーブが付加されます。

$ curl "http://localhost:2014/scramble/.txt?e=333ni*3"
D2 L2 F D2 R2 B' L2 R2 B D L D B2 L' R2 D2 B2 F' U' B Uw'
D2 F D2 F R2 D2 B2 U2 F D2 U2 R B' F L F U' R F' D' U Rw2 Uw'
L2 R2 B2 U2 B' D2 R2 B U' L2 D L D' B' R' U2 B' F2 R2 Fw' Uw

最少手数競技のスクランブルです。 今回のバージョン (TNoodle 0.11.1) から、FMC の前後には “R’ U’ F” が必ず付くようになりました。

$ curl "http://localhost:2014/scramble/.txt?e=333fm*3"
R' U' F D B2 D' B2 L2 D U L2 B L D' B' F D2 F' U' B2 F' R U R' U' F
R' U' F U2 F2 D2 R U2 F2 L2 D2 U2 L' U F D2 R2 U R' D B' L2 D F' R' U' F
R' U' F L2 F2 D2 F2 U' F2 D' R2 F2 U L B D U F U R2 F2 U R F2 R' U' F

---