Documentation for headless instance orchestration layer

I want to use the server-authoritative, session-based multiplayer capability of Nakama. It says we can use the orchestration layer to control headless Unity instances. That’s exactly what I need, but I can’t seem to find examples or documentation on this topic. How can I implement such a system?

Blockquote Session-based multiplayer: For complex gameplay where you want the physics running server-side (e.g. Unity headless instances). Nakama can manage these headless instances, via an orchestration layer, and can be used for matchmaking, moving players on match completion, and reporting the match results.


Hi @Umut , thank you for reaching out.

We’re still working on a guide / examples of using Nakama for session-based multiplayer to add to the documentation.

In the meantime, you can email us with details of what you are trying to accomplish and we’ll try to help directly.


Thanks for your answer. We want to develop a game like Clash Royale and already have a prototype made with Photon Bolt. But now that we also need to have a WebGL client, we wanted to use Nakama instead. We were using Unity’s own Navmesh/path avoidance system and sending position data with 30 tickrate.

I am aware that we can write our own pathing system and avoid using Unity headless server, is there an example project for server-authoritative pathing system? Pirate Panic is a nice example for such type of game but we want to simulate everything including pathing and path avoidance in the server to make cheating impossible.

Hi @Umut,

In general, when a studio wants to use headless game instances we recommend using a third-party service such as Amazon GameLift, Agones, Multiplay, etc.

With regards to your second question relating to server-authoritative pathfinding, we don’t currently have any examples for performing server-authoritative pathfinding. Typically pathfinding algorithms are highly game specific and not one-size fits all. In general, to support server-authoritative pathfinding you would want to use an engine agnostic pathfinding method such as the A* algorithm rather than say Unity’s NavMesh agents. You would then use this algorithm in conjunction with server-authoritative match handlers. Your server would have to be aware of your games map/grid/terrain data. How you provide this data to the server and parse it would again be game specific and not something we would be able to advise you on without knowing more about how your game is structured.

As @gabriel mentioned, if you’d like to discuss your games specific needs and how we might assist you please do reach out to us via email.

I hope this helps.

Kind regards,


I also love to see some example for MOBA, FPS or MMO, how can Nakama handle this?

Hi @gabriel !
Is there any updates about orchestration layer for headless mode?

Hi @brainode - This is still on our content backlog but no timeline yet for when we’ll be able to get to it. Will discuss with the team to see if the priority can be bumped up :+1:

1 Like

Hi @gabriel

I’ve developed a Node.js server to handle the dockerized Godot headless instances for server authoritative multiplayer and it worked.

Then I realized that, as an indie, there’s still much work to do except the gameplay, like accounts, matchmaking, social, storage, etc.

That’s why I reach out to Nakama.

I found the magic term “orchestration layer” in the document but that’s all I got. There are no detailed examples or documents.

My game is a 3D, space-themed, imposter game. The gameplay is like Dread Hunger but it’s space-themed.

How can I use the session-based feature of Nakama match handler?

Hi @juryxiong

As it says in the post directly above your own, there is currently no documentation with an example implementation. We do plan to add it to our documentation at a later date, but I do not have a definitive timeline to provide at this point.

If this is something you need the help of our engineers to implement, then that needs to be under a support agreement or professional services engagement.

Hi @gabriel

Thanks for the reply!

I did read the content in this post carefully. It dosen’t say it needs to be under a support agreement, it only says I need to send email. Maybe I didn’t read carefully enough.

Now I fully understand the only way I can use the the orchestration layer feature of nakama, is to pay as indicates.

Thank you again for making this clear in the post!

To someone who may concern:

Although a few, there exsit some mentions on how to integrate headless server with Nakama:


At least I have some clues on how to. I’ll try the integration.

If I succeed, I’ll share how I do it.


Basically I made it, still needs some tweaking.
After it’s fully completed I’ll write a tutorial


Integrate Godot Headless Server with Nakama


Thanks @juryxiong for sharing!

Thank you very much @juryxiong , very interesting, I’m sure this will help many of us :smile:

glad if it helps!