Dedimania forum

FAQ about new (ie TM2) Dedimania API
(Several infos in the FAQ for old api are still valid)


Where is the API described ?
Most info about the API are on: http://dedimania.net:8082/Dedimania


What url should be used by client scripts ?
Production (ie client public release) should always use url: http://dedimania.net:8082/Dedimania . The 8082 port is balanced to several real server ports.

For dev tests you can use http://dedimania.net:8081/Dedimania instead, which is not balanced (so it is using the real 8081 port), and so allow both to find it easier on http://dedimania.net:8081/stats , and it is far easier for me to check its logs on dedimania side if you need/ask me.


Is there a test database ?
No, there is no test database, but you can use test maps to avoid sending bad things on "real" maps. Either use your own maps, or see below.


Are there test maps somewhere ?
Devs can use these (Canyon) test maps : SL-droit1.Map.Gbx , SL-droit2.Map.Gbx , SL-droit3.Map.Gbx , SL-boucle1.Map.Gbx , SL-boucle2.Map.Gbx

You will notice that most of them have author and record times below the normal minimum time : as you can see it in Fast plugin, there is a special case for maps from authors 'nadeo' and 'slig' allowing them to have short times. If you don't set such exceptions in your plugin then use your own test maps.

Actually records are not automatically removed on those maps. I will probably add that later for SL-droit1.Map.Gbx and SL-boucle1.Map.Gbx... for now if you need it then just send me a PM (on maniaplanet or tm-forum forums) to ask me to remove them.


Replays in dedimania.SetChallengeTimes

Replays in Dedimania² are used to check that the coherence of sent map info and times, so avoiding several unwanted wrong records (ie times sent to the wrong maps). Xymph can confirm that all scripts have send such things (some scripts very often, others very rarely, but still...). VR and GR will also be used if needed when checking records against cheating.

3 things may be sent in the method :
- VReplay (mandatory): the Validation Replay of the best time (ie first) sent. Only 1 VR is needed, mandatory and only for the 1st sent time. If the best sent time is not the 1st in list, or if the VR infos are not in coherence with that best sent itme and with the given map infos, then all the sent times (in that method call) will be ignored.
Note: the client script should itself skip the best time(s) if it fails to get the corresponding VR.

- VReplayChecks (mandatory in Laps mode, keep empty in other modes): in Laps mode the client scripts are supposed to send best lap times, not the full race times. But the VR of the player will give the full race time. So, in the Laps mode specific case, the coherence checks with the VR need to send the full race ckeckpoints times, those of the race of the player for which the best lap time is sent (ie it may not be the best race time!).

- Top1GReplay (mandatory if top1 time, keep empty if it is known that it won't be a top1): GhostReplay for the same time as VReplay : send only if it is the supposed new top1 (ie the best sent time is better that the previous known top1), else send an empty string !


How the MaxRanks should be handled ?

Dedimania side:

- a best time will be stored if (new or improved) and (rec_new_rank <= server_maxrank or rec_new_rank <= player_maxrank)
The sent times are considered only if the best sent time has the same info as in the sent Validation Replay. A new Top1 time is considered only if the Ghost Replay with same info is also sent. Top1 replays are stored, and will be kept until the concerned record fall to a top rank below 4 or worse (the value is differ for VR and GR and will eventually change in future)

- an old record will be removed if (rec_new_rank > rec_maxrank)
(and rec_new_rank > player_maxrank, but the rec_maxrank is supposed to always be >= player_maxrank, so it's redundant)

Script side, sending times:

The normal way is to send all best times (with checkpoints as a comma list string, it's not as big as before when it was a xmlrpc encoded array) : Dedimania will store the right ones according to MaxRanks rules.
It is possible to send only new or improved best times (whatever ranks they are, so without looking for maxranks), but it will make stats about the map (ie TotalRaces and TotalPlayers) wrong, so better send all players' times as asked in the API.

Script side, live info and panels:

You can either not update panels in live, or update them whatever maxranks are, or try to handle the maxranks the same way as Dedimania do it to show what records will really be stored.

Btw you can't avoid some issues/wrong infos because of race conditions...
Example:
- player A is top30 and maxrank30
- player B has no top but is maxrank40
- player C is top 33
then, in this order (player A is not playing or does not improve is top) :
- player B make a top41 time -> at player finish it is rejected
- player C make a top28
=> player A record become top31 and so disappear, the old top40 become top39, the old top41 become top40, but it should have been the player B who made a top40 time (well... it's right that one can also consider that when player B made his time it was not top40, and it can be the reply if someone is whining about such case)  :p

It is a very special case, which is handled correctly (i hope) on dedimania side if all best times were sent (because they are all sent/received at the same time, so no race conditions).

As you see here, if your script send times based of MaxRanks handling on player finishes, you can miss some !
That's also why, if it is nice to show infos with MaxRanks handling is nice, the sent times should not rely on MaxRanks handling.