Zen Nihon GT Senshuken Server Technical Documentation 0.1
February 07, 2022
Shonumi aka D.S. Baxter

***************************************************
1. Introduction
***************************************************

Zen Nihon GT Senshuken (released as Top Gear GT Championship in the west) is a behind-the-car racing game for the Game Boy Advance. It served as a launch title in Japan and supported the Mobile Adapter GB for several functions including downloading custom racetracks and ghost car data, as well as uploading race result to get ranked.

***************************************************
2. Server Structure
***************************************************

Zen Nihon GT Senshuken is currently known to access the following URLs:

* http://gameboy.datacenter.ne.jp/cgb/download?name=/28/AGB-AGTJ/gtconfig.cgb
* http://gameboy.datacenter.ne.jp/cgb/download?name=/28/AGB-AGTJ/100.gtexcrs***.cgb
* http://gameboy.datacenter.ne.jp/cgb/download?name=/28/AGB-AGTJ/gtgst01.cgb
* http://gameboy.datacenter.ne.jp/cgb/download?name=/28/AGB-AGTJ/gtgst02.cgb
* http://gameboy.datacenter.ne.jp/cgb/download?name=/28/AGB-AGTJ/gtgst03.cgb
* http://gameboy.datacenter.ne.jp/cgb/download?name=/28/AGB-AGTJ/gtgst04.cgb
* http://gameboy.datacenter.ne.jp/****/gtrkconfig.cgb
* http://gameboy.datacenter.ne.jp/****/gtrk00.cgb
* http://gameboy.datacenter.ne.jp/****/gtrk01.cgb
* http://gameboy.datacenter.ne.jp/****/gtrk02.cgb
* http://gameboy.datacenter.ne.jp/****/gtrk03.cgb
* http://gameboy.datacenter.ne.jp/****/gtrk04.cgb
* http://gameboy.datacenter.ne.jp/****/gtrk05.cgb
* http://gameboy.datacenter.ne.jp/****/gtrk06.cgb


***************************************************
3. gtconfig.cgb
***************************************************

This file configures downloads for additional courses, Time Trial Ghosts, and online mobile rankings. gtconfig.cgb is only 200 bytes (0xC8) in size, as the game will not process any data beyond that. The format is as follows:

----------------------------------
File Structure
----------------------------------
0x00	 			::	Unknown data.
0x01				::	Enables Time Trial Ghost downloads for select race tracks.
0x02				::	Numerical suffix for downloadable course
0x03				::	Unknown data.
0x04 - 0xC3			::	Dynamic URL data for mobile rank files. Uses ASCII characters.
0xC4 - 0xC7			::	A 32-bit checksum for all bytes from 0x00 - 0xC3. All bytes are added, one-by-one. Checksum stored LSB first.

When downloading Time Trial Ghosts, the game will display 7 menus, 1 for each race track. For Byte 0x01, each of the bits from Bit 0 through Bit 6 controls whether an individual track is enabled. Setting the bit to "0" enables it, while setting the bit to "1" disables it. 

When downloading extra courses, Byte 0x02 is converted to Base 10 (decimal) and appended to the file name as a 3 digit number. For example, if the value of Byte 0x02 is 0x30, the game will download the file "100.gtexcrs048.cgb" for the course.

The dynamic URL data is an ASCII string terminated with a null character (0x00). The string points the game to the file gtrkconfig.cgb as well as the gtrk00.cgb through gtrk06.cgb files. Apparently, some portions of the string are ignored when the game makes the actual HTTP GET request. For example, if the string is "gameboy.datacenter.ne.jp/cgb/", the GET request only appears as "/cgb/". Any text prior to the first "/" character is effectively removed. This string is exclusively used for files related to mobile ranking.


***************************************************
4. gtrkconfig.cgb
***************************************************

The purpose of this file is similar to gtconfig.cgb. It controls which menus to display for online mobile rankings. It has a total length of 8 bytes. The last 4 bytes compose a simple additive checksum of the file's first half. The format is as follows:

----------------------------------
File Structure
----------------------------------
0x00				::	Enables mobile rankings for select race tracks
0x01 - 0x03 			::	Unknown data.
0x04 - 0x07			::	A 32-bit checksum for all bytes from 0x00 - 0x03. All bytes are added, one-by-one. Checksum stored LSB first.

When downloading mobile rankings, the game will display 7 menus, 1 for each race track. For Byte 0x00, each of the bits from Bit 0 through Bit 6 controls whether an individual track is enabled. Setting the bit to "0" enables it, while setting the bit to "1" disables it.


***************************************************
5. 100.gtexcrs***.cgb
***************************************************

This file represents a custom racetrack that can be downloaded from the servers and saved on the player's game cartridge. It is available through the Mobile Menu and selecting Course Download. A 100 yen service charge is attached to each download. The "***" part of the file name is replaced by Byte 0x02 of gtconfig.cgb when converted into a 3-digit decimal. The file length is 272 bytes total. The format is as follows:

----------------------------------
Racetrack Download Format
----------------------------------
0x0000 - 0x0003 		::	Unknown 32-bit value. Seems to be ignored.
0x0004 - 0x001B			::	10 character title plus terminating character. Uses a custom 16-bit character encoding.
0x001C - 0x010B			::	Racetrack data.
0x010C - 0x010F			::	A 32-bit checksum for all bytes from 0x0000 - 0x010B. All bytes are added, one-by-one. Checksum stored LSB first.

The format of the racetrack data is identical to the same data saved on the cartridge when a user creates their own custom track. Each racetrack consists of a 10x6 grid wherein blocks of the track are positioned. The binary data for the racetracks allocates 4 bytes for each block. Blocks are arranged left to right, top to bottom. The format is as follows:

----------------------------------
Racetrack Block Format
----------------------------------
0x00				::	Block Type. 0x01 = Straight Track, 0x02 = Turn, 0x03 = Starting Position.
0x01				::	Turn Type or Starting Position Type.
0x02				::	Must be 0x01 to signal a valid block.
0x03				::	Not used, reads 0x00.

Depending on whether the block is a turn or a starting position, Byte 0x01 has different meanings. They are listed below:

----------------------------------
Block Turn Types
----------------------------------
0x00				::	East-to-South turn.
0x01				::	South-to-West turn.
0x02				::	West-to-North turn.
0x03				::	North-to-East turn.

----------------------------------
Block Starting Position Types
----------------------------------
0x00				::	Start race facing East.
0x01				::	Start race facing South.
0x02				::	Start race facing West.
0x03				::	Start race facing North.


***************************************************
6. gtgst00.cgb - gtgst06.cgb
***************************************************

These 7 files represent menus for different ghost data that can be downloaded. From this menu, the player can choose a specific ghost from a specific track and then proceed to save it to the game cartridge. Each file 0x9E4 bytes long. Together, they give the player access to 210 sets of ghost data for each of the 7 race courses available (30 per track). The file for each .cgb file is as follows

----------------------------------
Ghost Menu File Structure
----------------------------------
0x0000 - 0x0001			::	Year of last update, LSB first.
0x0002				::	Month of last update.
0x0003				::	Day of last update.
0x0004 - 0x0007			::	Unknown data.
0x000A - 0x09DF			::	Ghost Data Entries.
0x09E0 - 0x09E3			::	A 32-bit checksum for all bytes from 0x0000 - 0x09DF. All bytes are added, one-by-one. Checksum stored LSB first.


----------------------------------
Ghost Data Entries
----------------------------------
0x00				::	Unknown data.
0x01				::	Weather condition for ghost data (0 = Sunny, 1 = Rain). 
0x02				::	Car type used for ghost data.
0x03				::	Car transmission used for ghost data (0 = Automatic, 1 = Manual).
0x04 - 0x0B			::	Unknown data.
0x0C - 0x0D			::	Handicap Weight. 16-bit value stored LSB first. Max value is 990, game displays values as units of 10 (e.g. 10, 20, 30, 40...) May be zero.
0x0E - 0x23			::	Ghost Name. 10 characters plus terminating character. Uses a custom 16-bit character encoding.
0x24 - 0x27			::	Ghost Time. 32-bit value stored LSB first. See notes below on format
0x28 - 0x33			::	Unknown data.
0x34 - 0x55			::	URL to download the ghost data. Uses ASCII characters.

Each Ghost Data Entry takes up 84 bytes. Once the player selects an entry, the game goes on to download the file specified by the URL. The URL in the entry is limited to 32 characters. Ultimately, if the URL is something like "myghostfile.cgb", the game ends up downloading from the following address:

http://gameboy.datacenter.ne.jp/cgb/download?name=/28/AGB-AGTJ/myghostfile.cgb

The total time used for the ghost is stored in a 32-bit value. The overall time works based on 1/100s of a second. To calculate the total time, start counting at zero and add according to this table:

----------------------------------
Ghost Entry Time Format
----------------------------------
0x00				::	Time = Time + (1/100) * Byte Value
0x01				::	Time = Time + (256 * (1/100)) * Byte Value
0x02				::	Time = Time + (65536 * (1/100)) * Byte Value
0x03				::	Time = Time + (16777216 * (1/100)) * Byte Value

The maximum time alotted for any Ghost 99 minutes, 99 seconds, and 99 hundreths of a second.


***************************************************
7. Ghost Data
***************************************************

The actual Ghost Data downloaded from the servers is saved to Flash RAM inside the cartridge. A fairly large portion of the 64KB of backup data is reserved just for Time Trial ghosts, and out of all the downloadable content, Ghost Data is potentially the largest. The file format is described below.

----------------------------------
Ghost Data File Format
----------------------------------
0x00				::	Race Track.
0x01				::	Weather condition for ghost data (0 = Sunny, 1 = Rain). 
0x02				::	Car type used for ghost data.
0x03				::	Car transmission used for ghost data (0 = Automatic, 1 = Manual).
0x04 - 0x0B			::	Unknown data.
0x0C - 0x0D			::	Handicap Weight. 16-bit value stored LSB first. Max value is 990, game displays values as units of 10 (e.g. 10, 20, 30, 40...) May be zero.
0x0E - 0x23			::	Ghost Name. 10 characters plus terminating character. Uses a custom 16-bit character encoding.
0x24 - 0x27			::	Ghost Time. 32-bit value stored LSB first. See notes above on format.
0x28 - 0x33			::	Unknown data.
0x34 - EOF			::	Track Movement Data.

The format for the metadata is largely the same as the ghost menu. Byte 0 is used here, however, to define the specific race track the ghost belongs to. This forces the game to run that exact course, regardless of which menu it was downloaded from online. A list of all possible options follows:

----------------------------------
Ghost Race Track Values
----------------------------------
0x00				::	Twin Ring Motegi
0x01				::	Fuji Speedway
0x02				::	Sportsland Sugo
0x03				::	Ti Circuit Aida
0x04				::	Central Park Mine Circuit
0x05				::	Suzuka Circuit
0x06				::	EDIT - 1st custom course name
0x07				::	EDIT - 2nd custom course name
0x08				::	EDIT - 3rd custom course name
0x09				::	Twin Ring Motegi (Mirror)
0x0A				::	Fuji Speedway (Mirror)
0x0B				::	Sportsland Sugo (Mirror)
0x0C				::	Ti Circuit Aida (Mirror)
0x0D				::	Central Park Mine Circuit (Mirror)
0x0E				::	Suzuka Circuit (Mirror)
0x0F				::	EDIT - (Mirror) 1st custom course name
0x10				::	EDIT - (Mirror) 2nd custom course name
0x11				::	EDIT - (Mirror) 3rd custom course name

Time Trial Ghost Data can apply to custom courses as well, thus allowing players of Zen Nihon GT to both download a unique track from the server as well as a ghost for it as well. Mirrored versions of each course is also available.

The Track Movement Data is a recording of a car's movements along the race course. For the downloaded file, it has the exact same format as regular Time Trial ghosts made locally by the player and saved on the cartridge. Zen Nihon GT essentially copy + pastes this section to Flash RAM as is.

No checksum is need for this file. The Track Movement Data uses 32-bit checksums periodically (approximately once every 4KB) to ensure data integrity, however.


***************************************************
8. gtrk00.cgb - gtrk06.cgb
***************************************************

These files are the online mobile rankings. Players could sumbit their completion times for a certain race track (in the form of a Time Trial Ghost) and the fastest times would be listed for all to see. It was essentially a somewhat static leaderboard, as it required the player to manually send data to the servers. The exact URL is specified by the first string in gtconfig.cgb. Each file is 0xA34 bytes long. The format is as follows:

----------------------------------
Mobile Ranking File Format
----------------------------------
0x0000 - 0x0001			::	Year of last update, LSB first.
0x0002				::	Month of last update.
0x0003				::	Day of last update.
0x0004				::	Hour of last update.
0x0005				::	Minute of last update.
0x0006 - 0x0007			::	Unknown Data.
0x0008 - 0x0A2F			::	Mobile Rank Entries.
0x0A30 - 0x0A33			::	A 32-bit checksum for all bytes from 0x0000 - 0x0A2F. All bytes are added, one-by-one. Checksum stored LSB first.

Each file corresponds to a different race track and contains 50 entries. Each entry is 52 bytes long. The format of these entries (nearly identical to Ghost Data Entries) is as specified:

----------------------------------
Mobile Rank Entry
----------------------------------
0x00				::	Unknown Data.
0x01				::	Weather condition for ghost data (0 = Sunny, 1 = Rain).
0x02				::	Car type used for the race.
0x03				::	Car transmission used for the race (0 = Automatic, 1 = Manual).
0x04 - 0x0B			::	Unknown Data.
0x0C - 0x0D			::	Handicap Weight. 16-bit value stored LSB first. Max value is 990, game displays values as units of 10 (e.g. 10, 20, 30, 40...) May be zero.
0x0E - 0x23			::	Player Name
0x24 - 0x27			::	Course Completion Time. 32-bit value stored LSB first. Same format as Ghost Time, see notes above.
0x28 - 0x33			::	Unknown Data. Appears to be three 32-bit values that must be non-zero.


***************************************************
9. Rank Entry
***************************************************

Players could enter their Time Trial Ghosts to participate in online mobile rankings. Zen Nihon GT transfers to Ghost Data to the server and the leaderboard would be updated. It is unknown if the process was manually handled by server administrators or if server-side software automatically parsed and sorted the fastest times. The game transmits the data as part of an email attachment via SMTP. The format of the sent email is as follows:

From: xxxxxxxx@yyyy.dion.ne.jp
To: 
Subject: GT-CHAMP-ENTRY
X-Game-code: AGB-AGTJ-00
X-Game-title: GT-CHAMP
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="--AGB-AGTJ"
----AGB-AGTJ
Content-Type: text/plain; charset=iso-2022-jp
Context-Transfer-Encoding: 7bit
-----------------------
【全日本ＧＴ選手権】でランキング登録が失敗している可能性があります。
-----------------------
----AGB-AGTJ
Content-Type: application/octec-stream; name="gtent**.cgb"
Content-Transfer-Encoding: base64
Content-Disposition: attachment; filename="gtent**.cgb"
DATA
DATA
DATA
----AGB-AGTJ--

The attached file varies depending on which race track was recorded in the Time Trial Ghost. The server will receive files from gtent00.cgb through gtent06.cgb.

The message, encoded as ISO-2022 JP translates to: "There is a possibility that ranking registration has failed in the [All Japan GT Championship]."
