練習用サーバへの接続方法およびxmlの仕様変更等について
２０１０年８月３１日
■WebAPIのエンドポイント(URL)の変更に関して
操作命令の送信API、及び、フィールド状況の取得APIのエンドポイントが変更になりました。
変更は下記の通りです。
◇ 操作命令の送信API
(旧) http://prefix/command.pl?machine_1=[操作命令文字列]&machine_2=[ 操作命令文字列]&machine_3=[操作命令文字列]
↓
[変更の概要]
– エンドポイントがcommand.plから/system/command/に変更になりました。/system/command/に続いて従来通りの様式でGETクエリを指定してください。
– 各チームを識別するためのtokenパラメータを付与する事を必須とします。tokenパラメータは各チームに事前に連絡されます。
◇ フィールド状況の取得API
↓
[変更の概要]
– エンドポイントがget_map.plから/system/map/に変更になりました。
■各高専での競技テスト実行に関して
各高専で事前に競技の動作テストを行うために、インターネット版の競技サーバを公開すると共に、本選用／テスト用アカウントを下記の通り発行します。
◇インターネット版競技サーバ
http://procon-online.net/
インターネット版競技サーバは、本選と同じ競技用サーバを使って構築された競技システムで、本選と同様の動作をするものとします。
インターネット版競技サーバを使用する際のprefixは「http://procon-online.net/」となります。
つまり、各種APIのエンドポイントは
– 操作命令の送信API –
http://procon-online.net/system/command/machine_1=[操作命令文字列]&machine_2=[操作命令文字列]&machine_3=[操作命令文字列]&token=[各チームの識別トークン]&contest_id=[仮想コンテストID]
– フィールド状況の取得API –
http://procon-online.net/system/map/contest_id=[仮想コンテストID]
となります。
競技用サーバは常時の稼働を約束するものではなく、メンテナンスにより一時停止する場合がありますのでご了承ください。
◇アカウント
– 本選用アカウント 1個
– 仮想コンテストアカウント 1個
– テスト用チームアカウント 6個
本選用アカウントは本選時に使用するアカウントです。本選時には各チームの識別トークンは、このアカウントのトークンを使用するようにしてください。
インターネット版競技練習用サーバで各高専が干渉なく動作テストを行うために、コンテスト自体が各高専用に仮想化されて用意されています。
新規ゲームの作成には仮想コンテストアカウントのパスワードを使用してください。
また、仮想コンテスト上で模擬試合を実施する場合は、各高専に発行されているテスト用チームアカウントの識別トークンを使用してください。
仮想コンテスト上の試合では、操作命令の送信APIとフィールド状況取得APIの呼び出し時にコンテストIDを指定する必要があります。
本選同様の命令の後に、contest_id=[仮想コンテストのコンテストID]という命令を付与してください。
（例）
http://procon-online.net/system/command/machine_1=[操作命令文字列]&machine_2=[操作命令文字列]&machine_3=[操作命令文字列]&token=[各チームの識別トークン]&contest_id=[仮想コンテストID]
http://procon-online.net/system/map/contest_id=[仮想コンテストID]
※本選ではcontest_idは必ずcontest_id=1としてください。
■APIのデータ構造の一部変更に関して
操作命令の送信API、及び、フィールド状況の取得APIで提供されるデータフォーマットを一部簡略化し、属性値による指定を廃止しました。
また、属性値の廃止に伴い、一部フィールド名の変更を行いました。取得できる項目数や内容の変更はありません。
◇操作命令の送信APIの応答（試合の進行状況）
<?xml version=”1.0″ encoding=”UTF-8″?>
<data>
<session>33</session> <!– 応答結果のセッション番号 旧session_id–>
<map>
<owner>1,1,0,1,2,….</owner> <!– セルの所有者 –>
<provision>12,0,0,0,4,20,…</provision> <!– 配水量情報 –>
</map>
<team>
<team_id>6</team_id>
<machine>
<number>1</number> <!– 旧machine_id –>
<position>820</position>
<ryoma>0</ryoma>
<carryover>12</carryover>
</machine>
…マシン３台分…
</team>
…６チーム分…
</data>
実際の応答サンプルはcommand.xmlをご覧ください。
◇フィールド状況の取得APIの応答
<?xml version=”1.0″ encoding=”UTF-8″?>
<data>
<title>ゲームタイトル（試合名）</title>
<total_session>当該試合の総セッション数</total_session> <!– ロボットの初期位置 –>
<map>1,1,1,…(省略)…1,1</map> <!– フィールド情報 –>
<site>
<id>チームID</id>
<domain>高専名</domain>
<name>チーム名</name>
<start_position>0,1,2</start_position>
</site>
…（6チーム分）…
</data>
実際の応答サンプルはget_map.xmlをご覧ください。
■各種エラー時のAPIの応答
チーム識別トークンに誤りがある、操作命令の書式が間違っている場合など、APIがリクエストを処理できなかった場合、
以下のようなフォーマットでエラーの応答を返します。
エラーの内容は<error>項目として英語のメッセージとして返されますので、参考にしてください。
（例）
<?xml version=”1.0″ encoding=”UTF-8″ ?>
<data>
<error>team token is invalid</error>
<status>NG</status>
</data>
///
使用ツールの説明に関して
■プロキシサーバを介しての接続
８月３１日現在以下のツールはネットワークに直接接続した状態（自宅、NAT、B-mobile等の接続）で利用下さい。現在プロキシサーバ経由での接続環境でも実行できるよう調整中です。
なお、各校が自作するプログラムに関しては各自でプロキシを越えられる機能を付加してください。（本選ではプロキシを経由した接続は行いませんので、この機能は練習をプロキシの内部からアクセスする場合のみ必要です）
プロキシが使用できるバージョンが完成した場合は各種クライアントツールは、標準でInternetExplorerの設定を使用します。
プロキシサーバなどを介してサーバに接続する場合は、InternetExplorerの設定で行ってください。
■MizugameMain.exeのチュートリアル
プロコン公式ホームページより最新版をダウンロードしてください。
８月３１日バージョンは「Mizugame_100831.zip」となっています。
これを各パソコンの適当なフォルダに展開してください。
このMizugameMainを使用すると、各高専独自に１つの試合を作成し進行することができます。最初にマップを作成し、そのマップに従って競技を開始します。コンテストIDおよびパスワード・トークンを間違わなければ、他の高専の試合と干渉することはありません。
（MizugameMainの起動には関してXNAは不用です）
以下に使用法を示します。
・MizugameMain.exeを起動
・コンテストIDに”各チームのコンテストID”、コンテストパスワードに”各チームのパスワード”を入力して「接続」をクリックしてください。
プロコンサーバに接続ができると「接続に成功しました。」と表示されます。
「試合情報（参加チーム、マップ等）の読み込みおよび開始準備」をクリックしてください。
自動的にゲームエディタが起動します。
「最新のチームアカウント情報をダウンロードします」と表示されるので「ＯＫ」を押してください。
なお、各チームのコンテストIDおよびパスワードは別途指導教員にメールで連絡します。
各チームのパスワード・パスコードは秘密厳守としてください。
・(しばらく待つと)ゲームエディタが自動的に起動します。
・右のパレットやマップをクリックしてマップを適当に編集して下さい。
・セッション数を設定してください
マップ情報、セッション数などのパラメータは必要に応じて保存し、あとで再利用できます。
・チームを選択してください。（チーム１に実行している高専を配置する事を想定して説明します）
・チーム２?６には（下の方にある）「練習用AI-1?12」を適当に選んでください。
AIは自動的にロボットを操作し移動・配水を行います。
・もし自分たちのチームを２チーム以上登録する場合は、選択肢の中から自分たちのチームで番号の重複しない違うチームを選択してください。
・もし同じAIを重複して選択したような場合は、試合作成時にエラーが出ます。
・「試合を作成（サーバに送信）」をクリックしてください。
・(しばらく待つと)OKをクリックし、
・ゲームエディタを「閉じる」で閉じてください。
・試合情報が読み込まれ、ビジュアライザが自動的に起動します。
・ビジュアライザについては特に操作せず、「競技開始」をクリックすると競技が始まります。
・チーム１が自分たちのチームとなります。
・現状、チーム2?6は自動的にAIで動くので、ビジュアライザを見ながら試合終了まで進行してください。
・試合が終わったらメインプロセッサの「ログプレイヤーを起動」をクリックしてください。
・ログプレイヤーが起動して、自動的にログを読み込んでいるので、スクロールバーを左右にドラッグして試合の進行尾状況を確認できます。
※Config.exeを起動してLanguageをEnglishに変えたのち、MizugameMain.exeを起動すると英語になります。
■コントローラMizugameSimpleControler.exeのチュートリアル
本プログラムは１チーム分３台のロボットを手動で操作するためのプログラムです。各ロボットに動作を指定して送信すると、サーバに反映させる事ができます。
コンテストIDおよびチームトークンを指定することでロボットを操作出来ます。
なお本コントローラはゲーム情報を取得して動作するため、開始後でなければ正常に動作しません。
各ロボットの操作に関しては画面を参考にしてください。
■本選でのネットワーク環境について
本選ではDNSの無い閉じたLAN環境で行うためサーバのAPIは
http://192.168.50.1/system/command/
http://192.168.50.1/system/map/
となります。
DNSが使えないので、各パソコンのhostsファイルに
procon-online.net 192.168.50.1
を追加することで、練習と本選を同じ環境で動作させることも可能です。
各チームには192.168.50.10以降のIPアドレスが二つ配布されます。
各チームの割り振りに関しては別途Webで公開します。
ネットワーク対戦用プログラム：メイン
プロキシー経由での通信に対応しました． 学内からの接続テストで必要な場合に利用ください．