Missing documentation/example for new matchmaker support (Allocate and Reserve)

[ntilborg]

Is your feature request related to a problem? Please describe.
The new matchmaking Allocate and Reserve calls (#660) are introduced recently, but explanation how to use them properly is missing in the official documentation. Flow diagrams are also not updated yet.

Describe the solution you'd like
I would like to request the following enhancements towards the documentation.

• An explanation how to use the Allocate and Reserve calls
• An update of the flow diagrams towards a matchmaking service
• An example of a very basic matchmaking service interfacing with the Agones infrastructure

Additional context
This is maybe a general addition on top of #927 where the SDKs for all platforms are being updated.

[roberthbailey]

A diagram was added in #933 but it isn't live on the website yet since version 0.12.0 isn't live.

[roberthbailey]

If you run cd build; make site-server from a clone of the repo you will see a website running on localhost that will include the diagram changes. If it isn't too much trouble, it would be nice to see if the website that will be published with the 0.12.0 release next week will address your concerns or if you feel like documentation is still missing.

[ntilborg]

I indeed missed out on that one. Yes that partly solves the documentation update, but it is still lacking background information for the allocation and reserve calls. My main concern is the way a matchmaking service design should look like to incorporate agones, in my opinion the documentation is still lacking in that area. I will play coming week with this new rc to indentify where the gaps are.

[markmandel]

You can always see the documentation for the development version of Agones at https://development.agones.dev/ (access via top right version drop down)

https://development.agones.dev/site/docs/guides/gameserver-lifecycle/ is the updated lifecycle flow diagram.

Does the updated Client SDK documentation here help as well? https://development.agones.dev/site/docs/guides/client-sdks/ ?

Maybe there are some details we can add to the flow diagram? Or maybe we can link to some descriptions on how matchmakers work from somewhere? (So we need to do more education on how matchmakers work maybe?)

I hear your point on the matchmaker example - an example of open match and Agones will come from one project or another at some point.

This is all great feedback - would love to hear more about what specific things we can do to improve our documentation in this area 👍

[ntilborg]

Thanks for the info, that helps. The updated flow diagrams already explain more indeed.

As far as I see only some details are missing in the new flow:

• In the flow with Register() I still miss how the "Game server pod" is transfering its IP address and port number towards the matchmaker. I expect this can be accomplished using the SDK.GameServer() call?
• Details when the reserved time is elapsed, does the matchmaker needs this info as well? How to ensure no race condition occurs when reserve time is near its end and the severs still gets allocated (when its not ready)?

Since it is very advanced it would indeed help me and the community to get an example with some more in depth explanation e.g. with open match for matchmaker implementation.

[roberthbailey]

In the flow with Register() I still miss how the "Game server pod" is transfering its IP address and port number towards the matchmaker. I expect this can be accomplished using the SDK.GameServer() call?

https://development.agones.dev/site/docs/guides/client-sdks/#gameserver says that SDK.GameServer() returns "the IP and Port the GameServer is currently allocated to" which can then be transferred to the match maker. The Register() call is something that would need to exist between the game server and the match maker, and is out of scope for Agones.

Details when the reserved time is elapsed, does the matchmaker needs this info as well? How to ensure no race condition occurs when reserve time is near its end and the severs still gets allocated (when its not ready)?

I think this is actually explained pretty well by the diagram. The diagram shows the Reserve() call and Register() happening in a loop, with a note that the duration used for Reserve() should be longer than how long the match maker requires Register() to be available for. If you do this, then the match maker can assume that any game server that called Register() within the availability window is ready for allocation (illustrated with the StartGameSession() call).

[ntilborg]

I agree, it involves some thorough reading of the documentation to understand all the concepts. Therefore documentation wise I'm satisfied. Shall I keep open the "example of a gameserver" as part of this issue as it is planned for the future?

[roberthbailey]

That sounds good but I don't have an eta for when we might have an example. I know folks are thinking about wiring up open match and agones, but I don't think anyone is working on it yet.

[markmandel]

From this conversation, I did want to add a call to SDK.GameServer() to https://development.agones.dev/site/docs/guides/gameserver-lifecycle/#matchmaker-requires-game-server-process-registration

Right before the Reserve() call, to make it explicit that information about the GameServer() was retrieved through that SDK command.

I just haven't got around to it yet -- but I think it would be a valuable addition.

(If someone else wants to jump on it, please do!)

[markmandel]

@ntilborg super late, but would love to get your input on the adjustment to the diagram I made on the above PR. I hope it makes the relationship between SDK.GameServer() and registering with the matchmaker clearer:

https://github.com/googleforgames/agones/blob/2320e204f1dc115cce112e8b3f1683ac0068257c/site/static/diagrams/gameserver-reserved.puml.png

[ntilborg]

Yes I indeed implemented it that way already in my own proof of concept. It's fine now, thanks!

[markmandel]

We're almost ready to close this - we have this example!
https://github.com/Laremere/space-agon

[roberthbailey]

@ntilborg - Now that @markmandel linked to an example of a simple game using open match and agones is there more you are looking for here?

[ntilborg]

Agree! This helps!