Dedimania forum

Feel free to express yourself on your favorite dedicated related tool.

You are not logged in.

#1 2011-11-28 11:38:05

TX-Slig
slig
Fast author / Dedimania maintainer
From: Traxicoland
Registered: 2006-11-23
Posts: 806
Website

New API: FAQ for script devs

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.

Offline

#2 2011-11-29 09:25:03

?????? ¬nocturne=-
nocturne
New member
Registered: 2011-11-29
Posts: 3

Re: New API: FAQ for script devs

Wow, talk about great timing..  I've been poking around at the old api info pages, trying to make sure everything was in order -- and was coming on here for one last look at the old docs before picking apart FAST.

Thanks Slig!  Definitely needed this.  Btw, I take it TheM has already contacted you about the DM implementation in MLEPP, or will the older tags from Flo's ML port work?

Offline

#3 2011-11-29 17:10:36

TX-Slig
slig
Fast author / Dedimania maintainer
From: Traxicoland
Registered: 2006-11-23
Posts: 806
Website

Re: New API: FAQ for script devs

No, the old Dedimania plugin for ManiaLive from Flo won't work.

TheM and w1lla are currently working on it (i helped them a little to find solutions for some unattended issues), they still have some features to support but it should come soon now (hey, i have not said any delay : just wait their announce). I just hope that the data size limitation in sqlite (which is used to send data in a threaded command) won't complicate things.

Offline

#4 2011-11-30 03:57:18

?????? ¬nocturne=-
nocturne
New member
Registered: 2011-11-29
Posts: 3

Re: New API: FAQ for script devs

Well, think we pretty much worked out the rest of the kinks, at least leading up to an initial release..  The threading makes things more complicated (doesn't work the same on different systems), and this will be the first test of it having to do any real work -- but I'm hopeful it'll work as a good example for future plugins.

There's a few things I still need to iron out, though, mostly dealing with the new api features.  Currently only new recs in the top30 are submitted, and I haven't really checked into the new implementation of the maxranks feature completely, and will have to do more tests...

So, we should just send all player's best times, including encoded VReplays, plus a Greplay for somebody if they attained a top1 time?  Or is it safe to assume that if a player has a better DM rec than their current time, it's safe to not send a time/replay for them at all?  Or does this screw up the online stats?  In that case, would it be allowable to just send the new, slower time along with corresponding replay row blank (with the exception of 'VReplayChecks' maybe)?  It'd help save a lot of processing time and bandwidth..

Offline

#5 2011-11-30 16:56:44

TX-Slig
slig
Fast author / Dedimania maintainer
From: Traxicoland
Registered: 2006-11-23
Posts: 806
Website

Re: New API: FAQ for script devs

About sent times and VR

You can eventually send only new/improved times (but of course it will lower the map and server stats).

Anyway, it is mandatory to send the VR of the best time sent (which should be the first in the list) : its goal is not only to save it (it is stored only if one of the best tops), but also to check that the sent map uid and times are in coherence with the sent VR (Xymph can confirm that occasionally -but that means far too many times- on TMO/TMS/TMN/TMF dedimania some client scripts send times for the wrong map).

The VR has 2 purposes : avoid unwanted wrong times (ie sent to wrong map), and give possibility to make a replay validation (hoping that as Nadeo says for years it would really detect cheats). The main reason to change the api was to add the VR.

The main purpose of GR is also to help again cheats by looking the replay. Btw the possibility to get top1 replays is a nice side effect wink


About threading

It is really better to do async remote i/o, to avoid having the script block all the time the request is done. There are 2 ways to make async i/o : using thread, or select() based.

The manialive threading is a very interesting feature for async remote i/o, and a logical way for a Dedimania plugin. The problem is that if some ML user don't use/activate threading support, then the remote i/o will be blocking, which is very bad.
The other possibility is to use select() based async i/o, like i made in my Webaccess class for Fast (and which is also used for dedimania in xaseco and foxcontrol).

Offline

#6 2011-12-01 00:26:11

?????? ¬nocturne=-
nocturne
New member
Registered: 2011-11-29
Posts: 3

Re: New API: FAQ for script devs

Ahh..  So we need only send one VReplay per set of records submitted, accompanied by a GReplay if the best time is a candidate for the top rec spot.  So, the replay assoc array submitted only contains the one row?  That'll make things much easier, hehe..

I'm thinking that as long as threading works in general, it should work out fine with submitting requests..  The only request of any significant size will be submitting times/replays, and even with threading disabled the request should run on the next execution loop after the remainder of the onEndMap functions are ran.  The rest of the requests aren't quite 'time sensitive', nor do they occur on particularly time sensitive events.  I just need to check if my edit to eventually stop if fwrite == 0 (occurs sometimes with a broken connection) survived the process, otherwise it could trigger an unending loop that could kill ML with threading disabled.

I was considering creating a 'lite' mode for testing purposes, that disables unnecessary calls (like playerconnect) and sending >MaxRank recs; though I guess I could implement it automatically after a set number of failed requests.

Offline

#7 2011-12-02 11:10:15

TX-Slig
slig
Fast author / Dedimania maintainer
From: Traxicoland
Registered: 2006-11-23
Posts: 806
Website

Re: New API: FAQ for script devs

nocturne wrote:

I was considering creating a 'lite' mode for testing purposes, that disables unnecessary calls (like playerconnect) and sending >MaxRank recs; though I guess I could implement it automatically after a set number of failed requests.

If the goal is to reduce the number of requests, note that several playerconnect methods can be send as one request.
Btw, it's right that in case the threading is not enabled and synchrounous requests are made, a degraded mode that send only GetChallengeRecords and SetChallengeTimes would not be a bad thing.


edit: i edited 1st post with infos about needed replays

Offline

Board footer

Powered by PunBB
© Copyright 2002–2005 Rickard Andersson