[HLAPI] Chaos and abysmal docs for Lobby, NetworkClient.Ready(), ServerChangeScene

Hello everybody,

I'm trying to implement multiplayer games into my existing game, utilizing the "shiny new" Tech of UNET and the HLAPI. I'm doing so for about a week, and having *a lot* of trouble with it to say the very least. I'm a "scripting reference" guy, so I admit that reading high level "that is how it is basically done" documents is not really my thing.

So, my general impression after about a week of trying to figure out the new 5.1 unity networking system is that there is A LOT of voodoo going on under the hood, that the system is far from finished and that the documentation of the whole system is abysmal at best, misleading at times and completely wrong at others.

Let me elaborate: I first tried to use the "NetworkLobbyManager" to come up with a lobby system to my network mode, trying to use it to implement a simple chat to take my first baby steps with this new tech. I failed miserably, because sometimes it would spawn the players, sometimes it wouldn't, so I gave up on it. I tried to do the same with a standard NetworkManager, as the NetworkLobbyManager stated it was "just derived and expanded on the NetworkManager". Wonderful. But there is no source code as to HOW NetworkLobbyManager was actually done. So you need to figure out a lot of stuff for yourself.

Like the "Ready" State. For some reason I was led to believe - maybe it's the name - that NetworkConnection.isReady is somehow related to this ready-message and that there needs to be some way to set it in the network. The Documentation states:

Wonderful, there is a way! Only there isn't. Because as part of the "misleading / completely wrong" part, THERE IS NO NetworkClient.Ready(). Neither on an instance, nor static. Great. Reading on in the documention. LIke Samples. Wait, there is a ready-Function called on ClientScene (which has no relation whatsoever to anything I've read so far, that's the "voodoo" part I was referring to). Let's check the sample in the docs of "ClientScene.Ready". Which, strangely, doesn't contain a single reference to "ClientScene.Ready". Well, there we go, THAT's how Ready is done!

Just: There is no "NetworkServer.Instance". There is no "NetworkClient.Instance". Both seem to belong to JS. There is no (public) NetworkClient.Ready, neither static nor otherwise. Fun fact: Both C# and JS contain a JS sample, so maybe that is just caused by that. .

My point being: WHAT EXACTLY did you document there? Because obviously it was NOT the system you delivered. I see you made a lot of fixes on the network system in 5.1.2, but none of them seem to cover anything I've written above.

More fun stories: When trying to use a [Command] or [ClientRPC] Method to send a non-serializable object (it was hidden in deep, classic coder mistake), Unity doesn't report the error. Or, it reports it "unity style": It crashes when trying to "weave" the network code. Unsure if it happens in 5.1.2, but it does in 5.1.1. More fun stories: When trying to send a byte array of say 70kb by Command or RPC, it is cut off at 7.432 bytes. without any information that it happens or why. I can imagine there is reasons. But why is there no documentation about this?

Another question that came up: I tried to execute this code:

Code (csharp):

1. [Command]
2. public void CmdStartGame( ulong seed ) {
3.     RpcStartGame( seed );
4.     NetworkServer.SetAllClientsNotReady();
5.     ServerChangeScene( "mainui" );
6. }
7. [ClientRpc]
8. void RpcStartGame( ulong seed ) {
9.     MainMenu.i.PrepareGameData( g );
10. }

And in my naivity I thought that "as a high level system, UNET certainly ensures that if I call an rpc first and ServerChangeScene after, the system will certainly ensure that all the RPC calls get send (and executed on the clients) first and only after that has happened, the clients will execute the message coming AFTER that", namely the scene change. Well, surprise, it doesn't work, seems like the scene change takes precedence, for whatever reason. I'm aware that there needs to be a lot of synchronizing going on behind the scenes, but in my opinion, that is basically the idea of "High Level" - to hide all the complicated stuff from naive coders like myself so coding actually gets easier when using high level stuff.

TL;DR: If you release a new coding API, the most important thing is NOT that there is as many features as possible, but that the documentation is complete and useful.

Otherwise, the best API will be just no use at all to anybody trying to use it. My Questions:

1) Could you please release the NetworkLobbyManager / NetworkLobbyPlayer sourcecode? It would be far better to learn what you do than the current samples.
2) Could you please update the documentation and especially the coding samples to actually contain the current state of your API, not something you most probably had it at in course of development?
3) Could you please explain how the "Ready" state stuff is working (or, supposed to work) and how ClientScene relates to all this?
4) What is a "client manager" - and how does it relate to NetworkManager?

Thank you for reading my rant, thank you for working out the things above, and thank you for possibly considering giving documentation a higher priority (and/or more qualified staff to do it). I'm a coder myself, and hate writing documentation as much as the next coder. But for an API, that is actually what differentiates "open source read the code for yourself and don't whine about docs" from "professionally executed and paid for". I read some disregard to open source comparison in another thread here, so maybe go the full way and not only be "better executed" than OS libraries, but also "better documented" .

 

I think your questions are good.

They do have a NetworkLobbyManager beta project now available to download from the Asset Store. Here is a forum post about it: http://forum.unity3d.com/threads/networking-lobby-example-beta-q-a.341592/

 

Good job. I mean that. It looks like you've been doing your research. The thing that you need to remember first and foremost, is that the networking libraries are not finished. Not even close. What you have access to right now is kind of like an Early Access game on Steam. You can make use of it, but it's not finished yet.

I completely agree that the documentation is hurting at the moment. There are irritating holes and just plain incorrect information (it was correct when written). When writing a library like this things change a lot. I'm surprised they wrote as good of a documentation set as they did. It's quite impressive if you look at it with full understanding of how complicated it is at it's base. When the libraries are closer to what you might think of as a "1.0 release" the documentation will be more full and complete.

I share your frustration but I'm exercising patience as much as possible. I'm currently (as of quitting time last night) stuck on trying to figure out how to reliably identify which player is which. This is something I think should be one of the simplest tasks possible, and yet I couldn't figure it out yesterday. Working with early access material is almost always like that though. I will figure it out. If I wait it will be as easy as I think it should be, but I will not wait. That's not the way I work

Edit: I didn't notice this post is a month or so old by now. I found this through a Google search. My post still stands though lol.

 

Thank you Nakor, I am still frustrated with the way things work, and even more so as I recently tried to make a patch release update of the editor because it fixes a problem which has annoyed me ever since I upgraded to Unity 5.1, namely disappearing Fonts when the Editor saves the scene or regains focus. Problem is, when I use that patch release to compile my game, the network mode simply doesn't work any more.

And regarding "Networking is early access": Sorry, but no, it is not. It HAS BEEN Early Access in the beta branch for at least half a year now. With Unity 5.1 it is in "RELEASED" state, at least that is what is claimed by Unity whenever they do actually release something, if it wasn't, it wouldn't have been in the thing they call "Release Unity 5.1". And as a Pro customer since 2.5, I expect something this nowadays behemoth of a software company claims to be "released" is also "production-ready". And with the documentation and the implementation in a state like that I am able to crash any server I write with about 20 lines of code that "should" work and aren't reported hazardous by the "NetWeaver" either.

Again, if it isn't release-ready, they have a superfine road map that they are able to reorganize as development dictates and if they just can't get it done right for a specific release, they can always push it back. Maybe you remember "Unity GUI", which was first announced for Unity 4.3 I believe, but took until 4.6 before they had it in a "release-ready" state obviously. So why not with the networking? Of course, because they wanted to get their "supplemental services" (read: revenue streams) out into the open as soon as possible. Even at the risk of *releasing* something that is "early access" at best.

Regarding your problem, I solved it this way: You have a "Player"-Object I suppose, every player should have a gameobject spawned by the server and created on all clients. The Player object that represents the local player has "hasAuthority" set to true, so you can always identify "your" playerobject. I used a syncvar on the playerobject to set the name of the respective player, so I'm consequently able to identify which player object is receiving e.g. an RPC. Hope that helped, if not, let me know

 

One thing that has been a consistently awesome when trying to figure out what's happening under the hood in Unity is Reflector or a tool like Reflector.

You can find the tool here: https://www.red-gate.com/products/dotnet-development/reflector/.

Have you ever used this tool Chris? It allows you to import and dissasemble assemblies (in this case the UnityEngine & UnityEngine.Networking) and see how they are implementing their classes like NetworkLobbyManager, NetworkManager, NetworkBehaviour, etc.

It has also been helpful when trying to figure out what their UNetWeaver is doing to generate the network code off of the HLAPI networking attributes. You can open up your project's Assembly-CSharp.dll and see what the code generation has done to your class.

 

Chris Crafty, I am finding I have a lot of issues, the same as what you mentioned above. It looks like they removed the NetworkClient.Ready API, but some of the documentation still refers to it, and I'm not really sure how to signal they are ready. Actually I'm finding it pretty hard to use the system, I basically have to study the assembly browser, clicking on networking classes and looking at available functions, and try to make sense of things. (Even then I can't get anything to work)

I think I have the very first step right. If its single player I StartHost(), if I'm creating a multiplayer game I create a match using the matchmaker and StartHost(MatchInfo). If I'm joining a multiplayer game I join a match and StartClient(MatchInfo).

However I'm a bit clueless on the next part. After joining a game the players need to configure some settings, after which they can signal they are ready. I would then want the server to tell all the ready clients to load a particular scene.

The NetworkManager.OnServerReady documentation says it is called when a client tells the server it is ready. So I basically override this function, and inside it I loop over all local and remote connections (clients) and check the isReady property. I also had to override the OnClientConnect API, as it wants to signal its ready as soon as it connects to the server.

It seems the way for a client to signal they are ready is as follows:

Code (CSharp):

1.  
2. ReadyMessage msg = new ReadyMessage ();
3. NetworkManager.Instance.client.Send (MsgType.Ready, msg);
4.  

My problem is that when I execute the code: base.ServerChangeScene ("MySceneName");

I get a warning in the editor:
Multiple EventSystems in scene... this is not supported
UnityEngine.EventSystems.EventSystem:OnEnable()

I guess I'm not allowed to change the scene within the OnServerReady function? Did you address this problem?

Also, I have no idea what the ClientScene class is or how its used.. wondering if you made any more sense of this.

 

Awesome, turns out my specific problem wasn't networking related, oops.

ServerChangeScene API worked as expected, my flow is basically like this:

1. I override the NetworkManager.OnClientConnect API so that clients don't immediately say they are ready as soon as they connect to the server.
2. Once all the client's have done their specific tasks (ie character selection or whatnot) and the user says they are ready, I send the "I'm ready" message to the server.
3. I override the NetworkManager.OnServerReady API so that every time a client says they are ready the server will check all local and remote connections. If everybody is ready, I call the ServerChangeScene API. This API tells all the clients that they are not ready and then begins to load a scene.
4. I override the NetworkManager.OnClientNotReady() API so that I get notified right before my client changes scenes. Not ideal, but so far it seems usable. In my case I do it to hide some UI that would otherwise stay shown, since my UI objects persist across scenes.

Now hopefully I can work on having a scene shared across multiple clients..

 

You can use NetworkServer and NetworkClient Handlers and do away with the network manager.. You would need to register messages so when someone connects it would start the message inside of that message you would have ClientScene.Ready.

 

hello!

i barely post in this forum due my "incompentence" in fact of coding. i'm a noob surrounded by experts. that said, excuse me ahead time for my silly questions.

i am already working on a project of mines by testing these new features (NetworkLobbyManager, in particular). the question is the following: how far can we trust these new features? i mean, implemeting this new Network Management System is wise or risky?

from what i read, and from what i "thought" to understand, the answer is "no". by myself, looking at the main Manual and Scripting References, i don't find anything that can help me to create my own code yet.

please note- i already have coded my own Lobby system looong time ago by exploiting the basics (Network, Arrays, that's). just lately i wanted to upgrade my software from 4.2 to 5.0 .. but i'm shocked.

kindly, what do you suggest me to do? what is the last verdict? "wait and see" or "try and risk"? i already wasted time enough to try to figure things out by myself with no success (i admitted this at the beginning).

thanks for your dealing and attention.
-arcady87

 

:::TO UNITY DEVS:::

I noticed that Raknet is still being used from one of my debugging tasks in Visual Studio as to what extent I do not know, I thought by now Raknet would have been tossed to the side already.. So the question is why are you still using it?

 

::To everyone else::
I have made my network solution free, You can find it in my signature look for Cross.Net click the bold letters and you will be connected to my site. The download is at the bottom of my site, I hope this helps everyone you do not need to use Mysql or anything else.. It should give a good insight on how to setup Unet.

 

Working on integrating the new networking API this week, and it feels like I just got stuck in traffic and slammed on the brakes. Better documentation on how to properly make your own wrapper/manager around Network.Server and Network.Client would be greatly appreciated, as well as documented bugs and fixes (hopefully networking is one of the focuses of the new weekly patch releases).

What makes this extremely tedious is that it takes a lot of time just to realize that documentation was incorrect or stale, and an equal amount of time just to realize that you are chasing a built-in bug rather than your own bug (matchmaking listings only showing up the first time, matchAttributes not being retrieved with listings, etc).

 

So out of curiosity, what are the Unity documentation employees doing all day for the past few months?

I notice they have multiple employees who are assigned to documentation. Is this the result of their combined effort?

I strongly suggest anyone trying to use UNET to stop wasting their time. Please do not waste your life only to end up scrapping UNET anyway. Skip the wasting time part and just go with Forge.

If you have already done a lot in UNET, I worked hard to try to make a tutorial to transition from UNET to Forge for those who already did a bit of work in UNET and don't want to just completely start over. I also explain some things and what functions Forge uses that UNET used, etc.

Nakor said it all, and then came back with an edit to say it still stands a month later. It's quite pathetic of Unity.

We should not have to suffer the flaws of Early Access even in our software! It's bad enough that it's effecting so many games. Unity considers this a "release" and does nothing to inform us that UNET is not at all ready nor is the documentation. I'm not sure what has changed, but honestly it seems like nothing has. These problems have been true ever since UNET's official release. It is quite frustrating and just goes to hurt Unity's image as a developer who does not care for the quality of their product like they should. Above all else, I am perplexed at what their full time documentation employees do all day if this is the result of their salary.

 

I actually had most of my online play working correctly with the old system, and I scrapped it because the new one sounded more promising and flexible, and to eliminate hundreds of deprecation warnings about the old system. I could theoretically go back (source control), but I find myself in a strange state of not knowing if Unity is dedicated to making the new system great sooner rather than later. Mentions of networking features are almost nonexistant in the roadmap, although hopefully "bug fixing" covers most of this.

I don't like to only complain - I wouldn't be able to make a game of this scope on my own (this efficiently) if it wasn't for Unity - but the 5.2 update was the rockiest yet (for me) and the networking API seems like it was released too soon. Even the cloud features are not that clear. Is their CCU moment-to-moment? Monthly? Can you use the matchmaking service and not the relay service, and keep CCU low that way? If I already have a perpetual pro license will that grant me the pro level CCU base when that is out of preview mode? It's hard to plan for release...

 

This is what spending your dev hours working with the HLAPI is like.

 

Um, ya'll got any more of 'em.... Corrections?

 

I might as well document them as a run across them... save some people some time?

 

Probably the last one for tonight.

 

Thank you for your time. These corrections are very helpful.

 

It's amazing that shadiradio has to do Andy Stark's job, even though he doesn't even get paid. Can someone please get these issues to Unity's attention? Someone isn't doing their job.

If nothing else, they should at least announce that Unity Multiplayer is in early access / alpha and it was wrong to declare it as a released feature.

Well, at least someone is working on Unity's documentation. Thanks shadiradio.

edit: Apparently they have 3 technical writers. Didn't notice that Hugh Longworth was another. I skipped Aleks Dubinsky because I assumed he does mostly "internationalization efforts" for the docs. The other two have no description other than that they work on Unity docs.

It's quite amazing that they have three full time employees working on their documentation, and this is the best they have. WTF are they doing all day? Step up your game Unity. You're wasting a lot of people's time with these outdated and horribly written documentation. It's like it's amateur hour over here...some of the docs aren't even logical! If shadiradio is right and you copy/pasted it, it would fail to even compile.

 

This is one of the main reasons why there's a separate Documentations subforum in the Unity Forums. We report errors and changes there only.

 

Wait...so the community does all kinds of work on the documentation?

Then what the hell do those 3 employees do all day every day?

 

They check the Bug Reports Bug Tracker for documentation errors. From the Documentation subforums, I realized there's a new bug category in Unity 5.2 Editor made for logging documentation article errors.

 

Thanks for the answer. I am dumbfounded by this entire debacle.

 

Yeah I didn't want to make this into an issue, but I don't really think I can bug report every single documentation error because, well, the entire Networking documentation is basically wrong or outdated. If you only ever plan on using the NetworkManager, then you might be ok, but all the other classes are basically referring to some kind of older/alpha version of the new system. I do think Unity will probably do a major pass over all this soon, is that assumption correct?

I basically just want to know that someone there knows that the majority of the HLAPI documentation needs help?

 

Theoretically yes, in practice no.

If there's too much stuff to do, priorities are placed. Documentation comes near last when there are API errors and crashes on PC and mobile devices. But all priorities will be stationed with staff looking, updating, and changing them.

I may expect they will update the docs for 5.2.2, but I should expect about 50% to 80% that they will for 5.3 on release.

 

Thanks for the info! I understand the prioritization, and as a customer I would value the API and bug fixes as the utmost priority. The HLAPI documentation has just been particularly poignant in the amount of errors. Thanks again!

 

What is needed is a map of the workflow for all network classes and methods, what order is everything called and in which override am I expected to do which kind of tasks. Currently it's trial and error by every development team. Which costs huge amounts of time.

My experience so far is that when you get it working it is quite nice, but to get to that point is hard

 

Agree 100%. A document(s) completely describing the workflow and lifecycle using the HLAPI (NOT the NetworkManager) would be tremendously useful. As FStar stated, most of my time with the HLAPI is spent as:

• Is this my bug or a bug in the API?
• Does this documented function/property actually exist?
• Am I doing something wrong or is this feature actually incomplete?

As a sidenote, working on a networked game without being able to launch 2 instances of Unity, coupled with the extreme amount of trial and error with this API, are horrible conditions for a happy work week. I've gotten around it with directory junctions in Windows to point to duplicate projects, but native support for working on multiplayer games should be a focus if ease-of-networking is a cornerstone going forward.

The scary thing is that it's not exclusive to multiplayer. If you decide to use this API, you are converting your single-player or local-multiplayer functions to work off this as a baseline as well (not necessarily online only), and it's really hard to trust this.

 

Let's try using the new Bug Reporter, and see what happens after a few more business days. It was confirmed officially that there are 3 employees looking over their Bug Tracker for Documentation errors.

You can use CTRL+B and editor to make two instances of Unity. The other alternative is to use a clone of your master branch, and launch two Unity editor instance separately. Just commit, and pull the changes to the clone branch after the master branch has been fixed.

 

Well guys, it's not just you. I'm having a bit of a struggle figuring out the right way unet developers would prefer us to work. It's so vastly open ended that it's a case of being lost.

 

This is how I used to work, but it is extremely time-consuming if you just change one line over and over (which is necessitated by the HLAPI at this point). That requires a rebuild and publish or a commit and pull when trying to iterate quickly. Since you can launch two instances of Unity, but it won't let you open the same project in both, what I did was duplicate the project and replace the "Assets" and "Project Settings" with directory junctions in Windows (mklink) and symlinks in OS X (ln). This lets me just edit my code in one place, without rebuilding or committing changes to version control. The only thing I have to do is let the script changes compile in each instance of Unity that is running, but that seems ok.

 

Sounds like a good bug report for Documentations for Unity: Tell exactly how Unity developers debug their network games on 1 PC, and how it should be done officially.

 

It makes me really wish that the Unity team was also working on a large scale game that used all their features (like Epic/Unreal). I know this would spread development thin, but that kind of setup really informs what is needed by the tools from an internal perspective (much faster than aggregating all outside user feedback over time). For example, they would know that updating plugins used in a project from the asset store is actually a nightmare (duplicate files, etc), and they would definitely feel the burn of the HLAPI docs. It might work best as an independent "customer" within the Unity team, so they use the tools and docs that Unity publishes before the public.

 

Yup. The learn team should just basically do a small MMO that takes them a couple of years. They'd never need to actually release this as a product, but use it as an ever-growing thing, maybe developing on it once per week. Regardless, so long as it grows, they'll learn more than small setpiece demos.

 

Hi. Considering transitioning existing networking code from Tasharen's TNET to the new UNET.
Q: Would you say UNET is production ready yet? Glancing over the docs it looks as if it has what we need to get it working, but reading this thread makes me think it's not quite done yet, nor properly documented? Is that still true in 5.2?

Thanks in advance!

 

From my experience, I would say it's really difficult to tell. The documentation is so out of date and incorrect that it's hard to gauge how solid the API is. Per your questions, it's a fact that it's not properly documented.

If you want to have two cubes synced up using the high level network manager, then yes, it works. If you are making a complex, real game and want your interactions to be flexible, polished, and robust, then I would say it's not ready for prime time (but it could be soon?). It's frustrating because it's not really documented on the roadmap - I don't get any sense of when fixes are planned, how high of a priority it is for upcoming patches, etc - which is scary if you are going to depend on this. It's also unclear about pricing tiers for matchmaking/relay, etc.

It really feels like flying blind right now, and is probably the most unpleasant experience I've had with anything Unity-related so far.

My #1 request is basically an in-depth flowchart/document covering how to use the HLAPI (not the NetworkManager) for all of the most common use cases. We need an overview of the network/connectivity lifecycle.

 

Stay Away from UNET.

I don't know what TNET is, but why are you wanting to transition exactly? Is there something wrong with TNET?

If you haven't already, check out FORGE. I switched over from UNET to Forge and it was a wonderful experience. They are also incredibly supportive and have excellent documentation. Updates are rapid.

 

I am also seriously considering switching to Forge. I should have time to experiment with it next week.

 

I wouldn't dream of switching. I'm staying with UNet because I know it will be supported and I've been stung with nonsense before.

 

I understand where you're coming from, but this is the first time I've felt the opposite of that with a Unity subsystem. Also I think Forge is a far cry from nonsense. I don't doubt that it will be improved over time, I think the question comes down to projects in development right now, and their release time tables.

 

I haven't got a comment to make on Forge or any other networking middleware, I didn't intend to come off that way. By nonsense, I mean the entire problem of being at an author's mercy rather than first party. Sure, Unity often sucks in a lot of places but the UNet team seem responsive on the forums, so perhaps a better idea is they hear our cry for much better HLAPI. So far it's quite lacking.

 

Unity updates are ridiculously slow, while quality third party updates are incredibly fast. I've even had fixes within a few hours of reporting a bug on most assets I buy. (Hint: I only buy assets from developers who are active like that and well respected.)

When it comes to networking middleware though, I don't blame anyone for wanting to stick with UNET because they don't want to get shafted. So many third party networking asset developers have abandoned or sold out their asset.

Forge is very invested in maintaining their product though because unlike most third party assets, and even unlike Unity itself, they are themselves invested in their asset because their game is being developed with it. This makes a huge difference for both the longevity and the seriousness / consistence of updates/fixes. It's why I wish Unity would be more seriously invested in making their own networking project (ex. a small MMO) because that would allow them to understand the flaws of their system and what is lacking a lot better than relying entirely on third party consumers to report bugs, etc. It would also improve the docs a lot because they'd need to use the docs themselves.

 

Totally agree.

 

I've also had really good experiences with some high quality assets (InControl and ShaderForge) - those developers have been an absolute pleasure to deal with, even as far as sometimes sending me quick fixes/updates without having to wait for the asset store update.

I understand though, I would much prefer to use the native API for such a critical system as networking, and like Hippocoder I just want the Unity team to be seriously invested in its future.

 

Quickie.

 

I've spent a week in the documentation and I've gotten about as far as a sloth up a tree. I can honestly say that I still have next to no idea what is happening with UNET and what I'm actually telling it to do.

 

Coming from someone who had this problem for the last 2 months and managed to understand it recently, the best way to overcome this is to do "experiments" on your own. Experiments full of "Debug.Log("Test");" codes.

I'll write up a post explaining how UNET works using ELI5 soon.

 

I thought I am too dumb to understand that documentation or cannot make it work but I see it's common problem and I would appreciate any kind of help @asperatology