SugoiDeCard/docs/wangan.md

# Wangan Midnight Maximum Tune

## Versions supported
- Full support and tested
  - Wangan Midnight Maximum Tune 3 (Export)
  - Wangan Midnight Maximum Tune 3DX+ (Export, Japan)
- Should also work just fine
  - Wangan Midnight Maximum Tune 3DX
  - Other regions (china?) of wangan midnight 3(DX(+))
- Not tested but should potentially work
  - Wangan Midnight Maximum Tune 1
  - Wangan Midnight Maximum Tune 2

## Versions not supported
- Wangan Midnight Maximum Tune 4 onwards (use IC cards already)

## Wiring info:

> Following is mostly an example, colors are reference of what I've seen on two
real arcade machines but might differ, pinout should be the same, however. Also,
only applies for Wangan Midnight Maximum Tune 3DX+, previous versions may or may
not have different connections and/or cable colors.

Game communicates with card reader using a standard serial (RS-232) interface, but
uses 3 pins and a non-standard (i.e. not D-Sub) connector. There is a 8 pin JST connector
on game's case:  
![Segment from WMMT3 operator's manual](./wangan_manual_screencap.png)  
Looks like this:  
![Photo showing the connector](./wangan_wiring_photo.jpg)
First 3 wires are for force feedback controller/motor, last 3 wires are for card reader
You'll need to disconnect those and connect them to device running SugoiDeCard and YACardEmu

Here's an example wiring for connecting to a DB9 connector:  
![Wiring diagram](./wangan_wiring_scheme.png)

RX and TX need to be connected cross-over (i.e. RX on game to TX on emulator and
vice-versa). Two pins on game side are left unused and not connected to anything

If you're planning on switching between emulated card reader and real one it's
probably a good idea to make a Y cable or additional custom connector just for
card reader side.

**NOTICE**: Sometimes game can get stuck showing an error for either card reader or
force-feedback which *will* persists between soft reboots, this can be fixed by
hard-rebooting (i.e. power-cycling) the machine.

## Concessions
### New card registration
Originally paper cards could be purchased from game itself for extra price, which
is contrast to buying modern IC cards from arcade operator or elsewhere. This makes
new IC card registration somewhat unintuitive - you'll need to scan your card, select 
"no card" and then "buy new card", even though game happily gives away cards in freeplay
mode.

LCD display will display instructions as a workaround for this.

Potentially, if game running is a decrypted/modified version, this could potentially be
fixed by messing with game's localization strings and sprites.

### Present/disused vehicle cards
Original paper cards had a "feature" that they have limited use of 60 games (cards themselves
physically can endure many more rewrite cycles, it's purely marketing trick) after which they
must be renewed (internally game calls it "overhaul" which makes sense in car tuning world, but
game itself never refers to it as that, I wonder why), in which you're essentially buying a new
card, and your old card becomes a "Present card" (or "Disused vehicle card" depending how far 
you were in story mode) which in theory you could give away to your friend and after they played
it for 5 times it would create one or several new cards with identical pre-tuned car on it.
Additionally, when renewing card you'll be able to pick a new custom color.

This whole ordeal is very nice and cool and potentially extracts even more money out of players,
and cards themselves can be a nice memorabilia but otherwise it's mostly annoying and useless.
Implementing it would also take extra effort as well as some hoops to jump through for the player,
so those are not supported right now. 

We might implement saving present card data separately, so that it could be transferred to a real
card if somebody *really* wants physical memorabilia.

### ＡＡＡＡＡ Player or pseudo-guest play.
Since original paper cards are purchased from game itself, card reader comes with a built-in
dispenser that arcade operator supposed to fill with blank cards (used cards also work), this
dispenser has empty/full status, so that when it's empty game won't "sell" new cards and only
allow either guest play or playing with existing card (as long as it doesn't need renewal).

Game seem to only read dispenser status at boot (and after dispensing a card?), which means
if you "refill" the dispenser (either real or emulated) you'll need to restart the game for
it to recognize that it can dispense more cards. As a result, we can't really force guest
play (unless we also hack into JVS?) if no card was scanned, so we do a pseudo "guest play"
meaning YACE will just write data to a dummy file (`dummy.bin`) and essentially discard all
of the save data created this way. This is mostly harmless but it might fill the high scores
and ghost data with players named ＡＡＡＡＡ.

## Game state estimation and issues.
Currently, our only source of information are card and shutter status of the card reader,
as result we can only guess what is actually happening with the game at the moment. This works
for 90% of supported cases but can get out of sync if anything unexpected happens. This also
means than initial state must be synchronized manually, i.e. currently it means you must start
SugoiDeCard when game is in attract (or similar, i.e. real guest play) mode. There are some
safety timeouts in some cases so that if it does get stuck you might get it un-stuck simply by 
waiting, but certain cases might require manual reboot.

### Note about renewal
Current version of SugoiDeCard does not have save data parsing, so it has no idea if card needs
renewal or not, since card renewal involves ejecting old card this eject must be ignored, otherwise
it would be treated as a "game over" and renewed card's data would be discarded. To account for this
we wait for a while right after inserting existing card and wait for ejection. In future we might
add optional (since save data is encrypted and you'll need to get keys yourself) save file parsing
to streamline the process.

### Stuck situations
#### Service/Test buttons
Going to service menu automatically ejects card, if this happened while SugoiDeCard was checking
for card renewal, it might get stuck in "playing" state indefinably (needs testing). Otherwise this 
ejection would be handled as a regular "game over". 

Going to service menu seems to leave shutter in whatever state it was in, i.e. going to service
menu at login screen ("Do you have a card?") will leave shutter open, booting SugoiDeCard in this
state will immediately switch it into "accepting card" state, but it should eventually fall back
to guest playing state and then to idle, if you just wait.

#### Unexpected situations
Any error with save data that could cause game to reject the card (i.e. trying to load japanese
save data on export game, corrupt data) would cause SugoiDeCard immediately switch to "card renewed"
state and possibly get stuck forever in it (needs testing and fixing)

Any connectivity loss (i.e. cable disconnecting, cab losing power/restarting unexpectedly) cannot be 
detected at all (as there seemingly no heartbeats between card reader and game board), and will most 
likely lead to a desynced state, although when game powers up it will automatically eject the card
so in case of unexpected reboot this ejection would be treated as a "game over".

If machine running SugoiDeCard loses power or if connection breaks, game machine will error out trying
to write the data, however it will write data to a internal backup (5 slots) which *could* be re-written
to card, but SugoiDeCard currently *does not support this at all*.