Search Unity

Feedback I think that Gen 2 examples need more context

Discussion in 'Documentation' started by moatdd, Jan 20, 2024.

Thread Status:
Not open for further replies.
  1. moatdd

    moatdd

    Joined:
    Jan 13, 2013
    Posts:
    178
    I've noticed a trend with Unity's documentation in relation to how I actually have to work with the software.

    Tutorials teach specifics in terms of using a command or feature in isolation but don't consider the implications of incorporation of that feature into a commercial product. If you want us to adopt 2nd generation technology into our products, you have to be thorough.

    As things are right now, you're selling us a hamster without informing us that we'll also need to get a cage, a water bottle, feed, wood chips and possible veterinary bills, and believe me, finding that out later on when it becomes an issue rather than letting us know what we've signed up for at the start is very unpleasant.

    It's not that I don't want to be the proud owner of a hamster, but being a hamster owner requires planning that is no less intricate than getting involved with Addressables, the new Input System, UIToolkit, SRPs, Localization, Entities, Netcode for GameObjects and Netcode for Entities, and so on.

    I am coming to you after three years of dealing with this as a solo dev and I'm kind of tired of going to the tutorials to learn something and receiving an experience like:
    upload_2024-1-20_16-34-36.png

    When I need something more like:

    So, case in point, let's look at the documentation for Addressables (and I'm only picking Addressables because it's the first, alphabetically. All the rest of Gen2 docs have this problem):

    https://docs.unity3d.com/Packages/c...21/manual/use-addresssables-introduction.html

    This intro gives a really detailed syntactic examples of how to use Addressables, including loading and unloading of assets by AssetReference, Address, and Label, but it doesn't explain how to USE the loaded asset itself!

    Let's look at one of the examples:
    upload_2024-1-20_16-43-9.png
    This example loads a prefab from Addressables, referenced via:
    Code (CSharp):
    1.     // Assign in Editor
    2.     public AssetReference reference;
    Since we're dealing with a prefab, it should actually use something more specific like:

    Code (CSharp):
    1.     // Assign in Editor
    2.     public AssetReferenceT<GameObject> reference;
    You want to use the specific AssetReferenceT<GameObject> to limit the field so that the picker only allows for GameObject prefabs marked as Addressable because otherwise the editor will allow you to assign a TEXTURE or SOUND or MESH or ANYTHING marked as ADDRESSABLE to that reference.

    And I would even go further by renaming the "reference" variable to "prefabReference". Demonstrate good coding practices by using descriptive variable names! Do you have to? No! But newbs learn from your tutorials and then I have to deal with them using nondescriptive variable names that they learned from you guys!

    Then this example runs into even further issues when it finishes loading the reference with:

    Code (CSharp):
    1.         if (obj.Status == AsyncOperationStatus.Succeeded)
    2.         {
    3.             Instantiate(reference.Asset, transform);
    4.         }
    Great! We instantiated the gameobject and attached it to our transform, but didn't retain any reference to it! So, we had better hope that there are no other children on this transform when it is time to clean this object up.

    Because, let's say that the prefab we just instantiated also has addressable references to things like, oh, I dunno, TEXTURES AND SOUNDS AND MODELS. How are those going to be handled? We have to preload those things as well!

    And what if this prefab contains a hierarchy of things which also reference addressables? How will those be handled?

    And when we go through OnDestroy(), what would the cleanup operation be like?

    Once you get into real-life applications this sort of thing can rapidly spiral out of control. It does not just go all Todd Howard "It just works™". This tutorial, needs to at the very least, hint at some of the pitfalls that you will encounter.

    And remember, this is not just for Addressables. (I have a bone to pick with documentation for Entities and Scriptable Render Pipelines and every single Gen2 tech that has come out in the last 3-5 years. I never get to work on gameplay because I have to deal with all the mess that the tutorials never touched.) You have to explain what happens if you use Addressables for things like shaders and sound effects. Like, what happens if you unload an addressable currently being used by a sound that is playing? Does the sound effect just cut off? Will it throw an errorspam?
     

    Attached Files:

    Last edited: Jan 20, 2024
  2. Lurking-Ninja

    Lurking-Ninja

    Joined:
    Jan 5, 2024
    Posts:
    466
    I think the rest of the post has the same relevancy as much as this name is the correct one. IDK who is Tom Howard and if he ever said "It's just works", but it's not the one known in gamer and game developer circles.
     
  3. moatdd

    moatdd

    Joined:
    Jan 13, 2013
    Posts:
    178
    TomTodd Howard, director at Bethesda. Makes a lot of promises, says "it just works" when it turns out that it doesn't. Practically a meme.

    But sure, let's derail my thread with your nitpick. If you want to get on my case for inaccurate naming you should just look at your own username. You should lurk more.
     
  4. Lurking-Ninja

    Lurking-Ninja

    Joined:
    Jan 5, 2024
    Posts:
    466
    I know, that what I was implying.
    You gave a feedback, I told that I think the feedback has the same relevancy as precise you were with one of the most known figure in the industry.
    It's a feedback, ultimately it's Unity's job to take it or leave it.
    But since you asked, I think you're asking for the wrong thing. Unity packages have reference-style documentation, which means it explains what commands, constructs you can use and they describe the usage of those. It is a very well-known construct of documentation among professional software engineers. Convoluting this with irrelevant details about not connecting implementation details of specific application is making that worse.
    What you want to see is in example games. And Unity is making those. Are there enough? Dunno, probably they would be never enough of those, we can always ask for more. Those example application can and should show off the best practices, how to use the commands explained in the reference documentation.
    Yes, reference documentation is in alphabetical order so you can actually find the command you're looking for.
    And again, when the command is instantiation, it doesn't talk about how to set it to the color red. It should talk about instantiation details and maybe reference counting tops. Whatever is connected to instantiation narrowly. Plus you have the other parts, the "how to" things, quick start, etc, those are there to put you on track if you're willing to read them.
    This is why I think you're asking for the wrong thing. But again, my opinion is just that, an opinion, Unity's stance is more important in this case.
     
    Last edited: Jan 21, 2024
  5. moatdd

    moatdd

    Joined:
    Jan 13, 2013
    Posts:
    178
    I don't just want some example game dropped on my head to reverse-engineer.

    I want the overview of tutorials to include things to consider in implementation. The overview is the big picture, the world map. The context. They should take their example games made with best practices and document the making of those games and then cross-reference instances of each feature in their manual. Why do we all have to reinvent the wheel of implementation of each feature? Or is this all so that asset devs can do that for us for a price?

    You can disagree with me but you better substantiate your argument. As it is, these "irrelevant details", as you call them, are vital when it comes to implementation in the same way that power tools have manuals and warning stickers to point out the dangers of their use.
     
  6. Lurking-Ninja

    Lurking-Ninja

    Joined:
    Jan 5, 2024
    Posts:
    466
    That is something you learn, not get shown. At least not the way you're describing it.
    IDK. Maybe, but if they are doing that because of this, they are doing it wrong since their income from the Asset Store is negligible...
    I just did. And I had good reason.

    Anyway, have fun, will see if Unity changes the documentation.
     
  7. Lurking-Ninja

    Lurking-Ninja

    Joined:
    Jan 5, 2024
    Posts:
    466
    We are doing this on the way we're, because it works. It helps you to find the crap you're looking for and not distract you with a bunch of unrelated BS.
    No, your laziness to look at practical _examples_ (that's why they call them examples) lead you to not understanding the difference. But it's easier to shout standing in the middle of the reference documentation that why they don't change it than open up a practical example and check it out how it's done. Like normal people do.
    Who's trying to gaslight whom again?
     
  8. moatdd

    moatdd

    Joined:
    Jan 13, 2013
    Posts:
    178
    Here's an example of relevant information that could've been included with Addressables in their overview rather than buried in somewhere in the Entities docs:

    upload_2024-1-20_22-9-24.png

    So, basically this means that I, a person who has been working with GameObjects might hear that it's a good idea to learn Addressables, spend a while folding them into my game, and then also learn that they should really be using Entities and spend a while learning the authoring procedures, and then set out to work with addressables in order to add DLC support to the game under Entity-based gameplay.

    And then I find out only much later on that Addressables are incompatible with Entities and require some other content management system. I don't know who these "normal people" are that you speak of, because I learn things as I need to implement them. Where are these practical examples that you speak of where Addressables and Entities are put together in the same game?

    They don't exist because these systems were never made to be compatible in the first place and there is no warning whatsoever in any of the overviews. This information is just there for me to discover when it comes time to weave the two together.

    Or, how about when it comes time to deal with UIToolkit and Localization systems? Except at the time of this writing, Unity has only recently added Localization support for UIToolkit to its most bleeding-edge beta build: https://docs.unity3d.com/Packages/com.unity.localization@1.5/manual/UIToolkit.html

    You would have known this if you were making games that used Gen2 stuff. I only want to talk to people who actually develop games using the Gen2 stuff and are looking to help improve the situation. Not people who are here to increase their post counts and pick fights, like you.

    upload_2024-1-20_22-19-18.png
     
  9. Lurking-Ninja

    Lurking-Ninja

    Joined:
    Jan 5, 2024
    Posts:
    466
    I actually knew these, it's only news for you. If you asked what you should use if you develop Entities, everyone and their granny would have told you to use Subscenes. It's not a secret. And this is why your approach "only read what I need in the next minute" is dead wrong. If you're planning to use a tech, read the overview, maybe even open up the relevant forum thread, plenty of info everywhere how to approach. And even you dissed your own post, the info is there. Not in the debated reference section, it's in the general info section which I also mentioned. So if you had sit down and read through the general info about Entities, you would have known earlier that you shouldn't use Addressables. You don't need that info in the
    Addressables.LoadSceneAsync
    command's example or whatever.
    WTF is Gen2?
    I understand, and I will shut up know, my opinion is known already three times over.
     
  10. moatdd

    moatdd

    Joined:
    Jan 13, 2013
    Posts:
    178
    So you just nuked your entire argument. I would have to have asked this rather than find out from the documentation. Which means that the documentation does not give all pertinent information that is privy only to people if you know which questions to ask. Except I don't really know if you know what you profess to know, because the whole time you never seem to have demonstrated it, and if you did, you're a lousy teacher and someone who uses their superior knowledge to own other people rather than help them out.

    No, it's not in the general info/overview of the Entities docs, it's in the Content Management subsection of the Entities docs.

    SRPs versus BIRP.
    UIToolkit versus uGui versus IMGUI (so technically, UIToolit is gen3)
    Entities versus GameObjects
    New Input system versus Legacy Input System,
    etc...

    Unity has been on a campaign to replace many of their legacy systems with newer technologies, often deprecating many of the legacy systems in the process. The fact that I have to explain this to you means you probably don't even know this.

    Thank you, blessed be to the heavens above! May you find great happiness in your life's purpose,
    somewhere else!!!!!!!!!!!!!!!!!!!
     
    Last edited: Jan 21, 2024
  11. moatdd

    moatdd

    Joined:
    Jan 13, 2013
    Posts:
    178
    upload_2024-1-21_0-13-33.png
    Unity Netcode example wants me to use the LEGACY input system instead of their new input system. Seriously? An implementation of the new input system would be more relevant.
     
  12. spiney199

    spiney199

    Joined:
    Feb 11, 2021
    Posts:
    7,819
    Sorry but... what?

    Why does it need to explain more? The point of the asset reference example is to show you how to load an asset. That's the entire purpose of the class. You load the asset, then you do whatever you want with it. It doesn't need to go into any more detail as that's entirely up to what the developer intends to do with the system.

    Any half-decent developer, learning or otherwise, can look at it and go "Okay, this is how I load an asset. I can apply this concept to my own situation where this solves a problem of mine." There's no need to handhold any further.

    The choice of input system here is also irrelevant to focus of the example. It's an example of how to use netcode, not any particular input system.

    There are definitely issues with Unity's documentation in places, but this feedback is almost beside the point of the documentation itself.
     
  13. Ryiah

    Ryiah

    Joined:
    Oct 11, 2012
    Posts:
    21,130
    I haven't read through the bulk of this thread because I'm just too tired at the moment and it's too many words but I noticed that @spiney199 referenced this so I'm going to point out the thing that I hate the most about the docs that we've been provided: the actual content between releases is highly inconsistent.

    You linked to version 1.21.19 but a basic rundown of how to use the loaded asset is in the docs for 1.20.5.

    https://docs.unity3d.com/Packages/c...ableAssets.html#using-addressables-in-a-scene

    I have a similar problem with the new input system. There are four workloads in most of the docs but in the most recent docs only three are listed. The embedded workflow where you reference InputActions in your script and modify them in the Inspector has been removed from the list.

    https://docs.unity3d.com/Packages/com.unity.inputsystem@1.7/manual/Workflows.html
    https://docs.unity3d.com/Packages/com.unity.inputsystem@1.8/manual/Workflows.html

    My most recent and very frustrating example was with overlapping elements in UI Toolkit. After extensive searching I found a solution involving absolute positioning but it was only mentioned in a docs entry that is very outdated but fortunately still online.

    https://docs.unity3d.com/Packages/c...tioning.html#using-both-relative-and-absolute
     
    Last edited: Jan 21, 2024
    AcidArrow and moatdd like this.
  14. moatdd

    moatdd

    Joined:
    Jan 13, 2013
    Posts:
    178
    No, there are still gotchas, such as when you have scripts that reference prefabs or objects that will not exist until the asset finishes loading, and you'll have to create the equivalent of a rube-goldberg machine that connect these references together. Plus, you're getting into the world of asyncs, which implies a different kind of thinking from single-threaded gameobject development. You call it handholding, I call it withholding.


    Again, you show your own inexperience with things you haven't used yourself. The LEGACY system is easy because you can access it anywhere you want because you can refer to it statically. But the new input system requires that you instantiate it

    If you want to use the new input system with Entities, you'll have to approach this in a very different fashion.

    In my case, I had to create a separate system to instantiate and poll the new input system and then store their values for other systems to read. So there would be an input system living on one entity for OTHER entities to get their values off of it. It's not like GameObjects where you can just put all the components you want onto every prefab you want. And I'm not asking for some esoteric thing, to be able to use the new input system with entities, and info on how to do this is not in the manual.

    I hate how all the know-it-alls I've encountered turn out to not know-it-all and are less than half-decent developers out to flaunt their superiority and/or pick a fight. Most actually knowledgeable people I meet tend to be helpful in some way or another, but being a jerk is just how the rest self-report. If you want to fight, go back to Twitter.
     
    Last edited: Jan 21, 2024
  15. moatdd

    moatdd

    Joined:
    Jan 13, 2013
    Posts:
    178
    Yes! The workloads are the practical and vital info that should really be put into overview sections like Getting Started. Even if they simply link it at the bottom and say: "For further reading, see: <links to other workflows>". Vital information is often buried in the docs.

    I can hear the know-it-alls going: "you should read 100% of all the docs then!" To which I say: fine, you should read all the docs of C# before you start using it. The thing is, I don't retain everything I read. I retain everything I *USE*, so I read a little, use it so I don't forget it, and then read some more when I need to know more, and then I use that, and so on. Not everyone has a photographic memory that can memorize all the docs in their entirety, let alone memorize all bits of information that aren't relevant until that particular situation arises. If you possess such a memory, congratulations. I'm happy for you. Don't be a jerk about it.
     
  16. spiney199

    spiney199

    Joined:
    Feb 11, 2021
    Posts:
    7,819
    Async code isn't particularly difficult, and it's single threaded in Unity. Hell, async code is just enumerators, just like coroutines!

    Not sure what the rest of that part is about. Sounds like you maybe designed things poorly and created your own issues.

    I mean I learnt to use Addressables and the new Input system within a few months of starting to use Unity. They're not particularly difficult. I'm sure I could learn to use Netcode and Entities whenever I have the need for them.

    Also your stance kinda just eventuated into calling everyone else a bad developer. Not a great look.
     
  17. moatdd

    moatdd

    Joined:
    Jan 13, 2013
    Posts:
    178
    I went through several rewrites of some sections after running into problems that I wouldn't have run into if the gotchas were clearly outlined in the docs.

    Also, async code is not "just like coroutines". If you set up an async to delete an object after a few seconds delay and then exit play mode, it will delete your object in edit mode. Coroutines also sit on the main thread while asyncs use the job system. It means that if a coroutine were to hang in an infinite loop, your game would grind to a halt, whereas, if an async were to hang on an infinite loop, your game would continue with that infinite loop running in the background.


    Let's see you try! I don't want to hear from you until you do.

    Are you trying to provoke a rise out of me? Why are you even here on a weekend? Sometimes victims of abuse will get so used to abuse and confrontational situations that after they leave their abuser they'll go to great lengths to provoke the ire of complete strangers around them because being in a civil environment makes them very uneasy. Sort of like how sometimes, long-term convicts who have served their sentences will commit crimes so they can get back into jail because living free is too different for them to bear.

    Literally no mentally healthy person that I know would spend their time going around on forums to try and dunk on others in this manner when there are so many better things to do. I'm really sorry for your condition but it's far beyond my pay grade and I do not have the necessary credentials to treat you.

    May you find peace and healing. Somewhere else that isn't here, Twitter (or Mastodon.)
     
    Last edited: Jan 21, 2024
  18. spiney199

    spiney199

    Joined:
    Feb 11, 2021
    Posts:
    7,819
    What? No it won't. They would be different objects. The scene you play in play mode is a different instance to the one you edit. It would probably throw a missing reference exception, actually, because the object it's reference has been destroyed.

    Also... not true... Aync code in Unity is handled by a special synchronisation context, which you can see here in the code reference: https://github.com/Unity-Technologi...port/Scripting/UnitySynchronizationContext.cs

    Async code still just runs on the main thread in newer versions of Unity, which is what allows us to use it along with the rest of the Unity API. There's no Job system happening here.

    Starting to feel this is less about issues with the documentation and more due to some strange ideas you have about how Unity works.

    I'll do it when I need to use them. Right now, I don't need to use them.

    Never used twitter. Don't use any social media, actually.

    Any way your posts are starting to sound a little... unhinged. I'ma leave you to your nattering.
     
  19. zombiegorilla

    zombiegorilla

    Moderator

    Joined:
    May 8, 2012
    Posts:
    9,051
    Closed because:
    a) pointless arguing
    b) documentation != training materials/tutorials.
     
    spiney199 likes this.
Thread Status:
Not open for further replies.