Tuesday, April 10, 2012

there is unrest in the forest

        You know, the thing with Unity is not so much the presence or lack thereof features, it's the same issue alot of software has, and that's the lack of not just documentation, but useful, relevant documentation.  I feel like too many companies assume that it's ok to just put out basic documentation for new users and then let the community pick up the slack.  That's alright I suppose, but that doesn't mean you can slack on the basic documentation.  For instance:
function GetHeight (x : int, y : int) : float
Gets the height at a certain point x,y
Really?  A function called GetHeight() that returns a height value?  No Shit?  How about some information about the input parameters?  What is the expected range of values, for instance?  How about the return value, what do the units come back as?  You know, little things, back to that whole idea of useful and relevant, right?  Sheesh.

...Captain Obvious is Obvious, Captain...

        My ire comes from a perfect case, one of today's tasks was to spawn trees on a Terrain based on the heightmap.  All the pieces are there, it's actually quite a simple process, but again, it's just not knowing the little things that results in probably a bit more experimentation than necessary.  Really I'm just whining, but i've run into so many cases of this sort of thing with so many software packages I've used (looking at you, Maya), that at some point you just wanna contract out and document the stuff yourself for them.

        So rant over, if you're interested in doing this sort of thing yourself, here's some code that might be useful:

        Obviously you'd want to add some sort of noise to the tree placement and maybe even add some simple tree variants so it doesn't look like a military haircut, but this code produces a good starting point, something like this:


        You could probably get even more headway by sampling other maps or attributes to add a bit more spottiness to the placement or maybe even do a radial tap per sample step, something like that. Dunno, if you make any useful changes to this, let me know! Otherwise I'm just going to do it myself and...well, i guess that's not that bad.


  1. Captain AnalRetentive to the rescue! You missed an open parenthesis in your Start method :p

    void Start) <--

    I definitely feel your pain vis-a-vis the documentation. There are a lot of things in there that look exactly like (or worse!) than your GetHeight() example.

    One thing you might want to do with the code is to cache your terrain width and height to a variable before the for loop. The execution speed might not differ /too/ much (I think Aras gave some numerical examples a while back), but for a larger script it might (also easier to read! :D).

    I know you already pointed it out, but just for posterity, I'd also add in some minor variation to the placement and scale (Random.insideUnitCircle, Random.Range()).

  2. The Terrain APIs are an extreme case in my opinion--they're some of the worst in the engine. For example, you probably discovered on your own that trees use homogenous coordinates, that map indices are row-major, how detail resolution works, etc., etc. Thankfully I think they at least added documentation in 3.5 indicating that detail textures added at runtime must be uncompressed in order to properly get packed into an atlas texture (or at least they told me they would last beta cycle). Slowly but surely getting better...you get the picture ;)

  3. This comment has been removed by the author.

  4. Yeah it seems to be a trend in software/api documentation across the industry, definitely calling out Maya there too:


    The other thing that really irked me about the Terrain API is that it seems very purpose built, so i feel like fleshing out the documentation a bit is almost a necessity at that point because yeah alot of my experimentation was just getting all the numbers to flow in and out properly...argh!!

  5. The maxscript documentation is horribly guilty of this as well, with the added awesomeness of completely inconsistent method naming (even within the same struct!).

  6. This is why the position known as "Technical Writer" exists and are hard to fill properly. Just like "technical artist" it takes someone special to both understand WHAT it does, AND explain it to others in a useful, intelligent form.

    1. Oh man, tell me about it...i worked for two companies that had the foresight to hire technical writers and they more than paid for themselves. In fact, i'm not sure they were getting paid what they actually deserved!