A number of the pages in the UnityEngine Classes documentation end with (or include) the statement, “Override this function in order to provide your component’s functionality.”
For example, the documentation on the MonoBehaviour Update method says this. But “Update” isn’t a method in the MonoBehaviour class, nor any ancestor of that class.
In fact, when I type “override” where it would be proper as part of the start of a new method in a subclass of MonoBehaviour, my IDE (Visual Studio Code) prompts me with Equals, GetHashCode, and ToString. There does not appear to be any Update method I could override if I wanted to.
Anyone know the reason the documentation uses this language?
Yeah, bad wording, it’s not an actual C# override. You just define the method and it will be called like an event. You can even make it private and it will be called, so there is some code injection trick.
I teach Unity programming at my university. The students mostly love it, but they all complain that the docs are not as good as they should be. I actually had a graduate student refuse to be my Teaching Assistant because the Unity documentation is so bad they felt they wouldn’t be able to help the undergrads.
Fascinating. Been using Unity since 2012 or so and the docs to me always seemed fantastic, particularly when it came to example code. You immediately had a running example. What more could you ask for?!!I That became my gold standard of example code: show me how I use it, SHOW ME, don’t tell me.
Now the new stuff that comes out with packages is either completely worthless, or I just haven’t cracked its secret. The new packages-related docs are so hard to pump, the descriptions are so obtusely worded sometimes they make a 1970s man page look amazing. The new docs are hard to follow, cross-reference, there’s ZERO example code (criminal offense in my mind), etc… it just keeps making me think like I’m a web newbie and I haven’t found the seekret to them yet…
I think of “implement” being the closest analogy, but it isn’t the same “implement” as of a base abstract class or interface, so kinda confusing.
Another word might be the verb ‘supply,’ as in, “Supply an Update() method to get an update tick.”
I love this whole system but this oddity also makes me reluctant to inherit MonoBehaviours… it’s not that you CAN’T override these simple functions, but it is that a lot of Unity people don’t expect you to do that in a Component environment like Unity. It can confuse…
Now of course, most of the time forgetting to call base.Start(); is gonna have an obvious crash, but a lot of times the failure could be quite subtle and hidden in a low-frequency codepath waiting to bite you.
That’s very unfortunate, but the reality of documentation production will affect its quality. First, not everyone tasked to do documentation are great at redaction or teaching. Making others understand is more of an art. Also not everyone documenting is an expert in the topic, they have to do a lot of detective work and interview the always-busy developers. And finally maintenance of documentation is very time consuming and expensive. Not trying to patronize, just listing a few things I’ve noticed while trying to fix some documentation while I worked at some game engine company
“Supply” sounds good here. “Provide” would also work, I think.
My guess as to why the doc just keeps getting worse and worse is that Unity has probably noticed people read it less and less, which is kind of a death-spiral. I’m with you, Kurt: give me something I can run! I can learn by changing that. But these days, I can get tons of those (albeit including tons I wish would just get of my way) from other sources. Unity probably knows that, and just doesn’t see it as a good use of their money to pay a team of tech writers.
Thanks, folks, for chiming in on this. It was kind of bugging me.
Ignored how? You don’t get a notification/email about it or anything (namely as you don’t log into anything to report pages). It goes into their backlog to look at gets looked at at some point. I’ve reported important pages like FixedUpdate as it wasn’t clear it was meant to be used exclusively for physics, and those got updated some weeks later. 9/10 times for me they get updated in a few weeks.
Obviously, yes, not your job. But it’s just something if you spot something, report it, move on.
I’m glad you asked Spiney!!! Let’s talk about the CharacterController page shall we?
Dating back to October 2020 I have several times reported that the above example code is defective because it calls .Move() twice in one frame, leading to missed ground contact. I even provided an equivalent codelet to replace the example.
I even invited others to report it. No idea if they did or not but it doesn’t matter: the sample is still defective and calls .Move() twice.
I believe that closely matches my understanding of the definition of the word “ignored.”
Here is my work-around:
Yes, my sample does a little bit more, but you don’t have to use it. Just fix the example code please! Lots of folks come in here with ground contact issues, and more often than not they are using code they (or Brackey’s… his stuff all uses the defective code too) derived from that example. That one example has poisoned probably THOUSANDS of controller instances out there over the years. I’m sure lots of people “just leave it” and shrug thinking “Oh it must just be flaky…”
And isn’t that another moment when childhood’s innocence is lost? I remember the first time I found a bug in a piece of systems code that came from IBM. I thought, “No, this can’t be wrong. This was given to us by the gods!” But it was wrong. So I fixed it. Which was depressing to have to do, and changed how I felt about the products created by big institutions for the next 45 years (and counting).
On the other hand, it was ultimately uplifting because my fix worked. Which taught me something else: It taught me that we are the gods.
Perhaps you have not yet found a bug in your compiler / assembler?
Imagine… you swear the code you wrote is correct, you run it, you attach the debugger, and again and again you get wrong results… and you finally dig in and inspect the actual CPU instruction stream… and it is flat wrong.
That’s when you can safely conclude: there are no gods… it’s all just ones and zeroes all the way down.
Even better: I found a stuck bit in a register of a DEC FPU. It resulted in an IEEE single-precision positive floating point value that was very, very small. I wrote a lot of Fortran code that ran just fine because, of course, one never actually compares floating point values for equality.
Unless one knows those values will be something certain, like zero. Imagine my surprise when I knew my computation concluded with a value of precisely zero in a variable, but testing it for equality with zero nevertheless failed. Along something of the same lines you followed, I looked at the assembly code, debugged it, couldn’t believe it and, finally, actually twiddled the bits with all those up/down switches and neon panel lights on the faceplate of our rack-mounted PDP-11/70. I literally loaded the FPU with a zero, bit by bit, then read the register on the lights, and saw a bit I had put in as zero came back as one. Printing that value showed it to be something like .00390625, which was what it was in single-precision format. Close enough to zero that tons of code I had written before ran fine.
A brilliant reminder that what we consider 1 and 0 is really just a voltage level being perpetuated somewhere between a bunch of interconnected components. One bias resistor out of spec and your 0 mysteriously drifts up to a 1… but only if the computer has been on for long enough to warm up…
