Docs & Unused Animations

Posted: 30 Sep 2022

A while ago I found some neat unused animations and I’m currently scripting an entity to view those ingame to show them off. While doing, I’m taking notes and such for when I eventually get around to documenting Psychonauts’ script API, which is what I wanna talk about a bit.

(For the most part) the documentation already in the game’s script files is actually pretty good, especially for super common shared Lua functions such as those in base scripts.

It gets spotty in places though, and there’s basically no documentation of a lot of the actual engine-side API - stuff that calls back into the C++ code of the game. For those, I have to either figure it out manually or pull out Ghidra and reverse the function.

See? Nice docs!

Sometimes… not great, but that’s fine. The first argument is at least self explanatory but the second one not so much. This doesn’t seem super uncommon for functions that do nothing but wrap engine API functions.

This one’s slightly more egregious, it’s actually missing a couple arguments (presumably, it was written before they existed).

And naturally, some functions have no docs at all. This is all fine but the really frustrating pieces of in-code documentation are those that refer to Double Fine’s internal documentation.

It seems they had an internal wiki site for documentation and some of the comments in the code tell you to refer to it for more information, which we obviously cannot do because we are INTERLOPERS treading ground that was not meant for us.

This one is just an evil tease. That link is an intranet link so obviously it doesn’t work and don’t try it. Even internally it probably doesn’t work, the server is probably long gone… I’ll admit I’m curious if the actual files of the wiki survived though. Probably not.

This is the remark that got me rambling about this by the way. If they had a Timer FAQ, who knows what else was there???

We do have a folder for programming documentation in the 2013 Steam build but it’s just a handful of files regarding optimisation. Interesting, but not useful.

I think there actually is a single file in there that’s directly related to scripting documentation but it’s basically empty with a message that just tells you it’s deprecated and pointing you towards the internal wiki again.

Back to the matter of my own docs, the ones that we’ll actually be able to read, I did already start working on some at one point but those are completely invalid at this point. Too many new developments. Namely, I was writing them back when we had no script sources.

So all the info was either based on really bad decompiled or fumbled out from me reading raw Lua opcode listings. Needless to say, time to start over.

I’m actually not sure what I was doing either because I chose to focus on the most bizarre things. Who needs docs on how the GMen in Milkman work right now??? How does that help anyone??

I’m still not sure how to go about it. I was using ReadTheDocs, but I don’t think the old docs were really formatted well and I’m not positive the format of ReadTheDocs works well for this?

Something like the Garry’s Mod wiki would be really cool. I wish GMod’s wiki framework was open source.

I’m really bad at writing documentation. Probably because I never do it. Writing docs for someone else’s massive Lua codebase from 2005 as someone who can barely write documentation for her own projects is probably a bad idea but here we are.

I mean I’m pretty sure I thought this whole thing was probably not a great idea from the start but it’s turned out to probably be the most successful personal project I’ve ever worked on so maybe the docs will also be the most successful.

…probably not, but optimistic thinking like that probably helps.

Small update on the thing that I’m actually working on, it’s almost “done”, I just need to figure out how to put Raz’s helmet on his head but nothing I’m doing seems to work.

I wonder if anyone is able to recognise this animation just from this. It’s actually somewhat related to the last thread.

Anyway, making this is definitely making me think that alongside technical docs I should obviously make some actual tutorials on how to do certain things in scripting, like creating basic entities, how to make entities of certain types, etc.

I am still working on a set of demo mods, the idea of which will be to not only show off what modding can do but also show actual real examples of how to do things like replace textures, add/modify entities, etc. with explanations and well commented scripts.

Progress on that is slow because I’m not creative enough to come up with good ideas but I do have a list of a few that should be good. Maybe I can repurpose this animation cycler entity into one somehow. Probably not.

Something that would be super cool would be editor extensions and such geared towards Psychonauts Lua. I’ve been using VS Code, the basic Lua extensions for it get the job done but it’d be real nice to have something more specialised.

Getting way ahead of myself there though, writing a decent one would need good documentation of stuff first. Plus, not sure how worth it would be to write that for something so niche?

Obviously would be ideal to also have stuff for something like Sublime, which I’ve not used in years.

I also don’t know the first thing about how you write those extensions. Again, getting ahead of myself.

Anyway, the thing I was working on is basically done and ready to demo unused animations. Still haven’t gotten to get Raz’s helmet on his head though which is a bit unfortunate.

It’s a special thing where none of his animations actually pose the helmet, and it runs on a seperate animation so that they can dynamically adjust his goggles to be up or down. Here’s a cool debug display that shows his animation stuff!

As you can see, underneath his main animations playing at the top, there’s also an animation called “darthelmetup” that’s technically always playing, which controls his helmet and goggles. Under that are animations driving his backpack.

Maybe it’s just not possible and it only works on Raz? No idea, if I fix it between now and when I record these animations you’ll know by whether or not his hat works.

I also wish I had a way to display which animation is playing ingame? I’m not sure there’s a function to draw text onscreen from Lua (funny enough this is where documentation would come in useful).

There’s a function that can draw text in the world which looks like this, but the way it scales means it usually doesn’t fit onscreen how I need it to.

Then again, if there was a function to put text onscreen there’s a good chance it’d be disabled in the release build. DF were really thorough with making sure that debug drawing functions didn’t work in release. The function to draw this text is one of the only survivors.

And it wouldn’t even display properly for most people anyway because it’s affected by the positioning but that also affects the firestarting temperature gauge! That Astralathe thankfully has a patch for.

Actually that being said, if these debug displays work then any theoretical function to put text onscreen from Lua would probably go down the same path and would work. Still not sure if that theoretical function exists though.

Might have to dig around for anything in Ghidra later.

Because of so many functions not working in release the debug menu’s displays are unfortunately super busted, and it also means that those functions aren’t usable by modders for debugging their own code.

Though, as mentioned before, our old friend the Linux port is built in debug mode! It has all those functions working! If you somehow accessed the debug menu on Linux it’d be basically fully functional, display-wise. Unfortunately no Linux support in Astralathe.

Though the fact the code is there does mean I might be able to do some really awful Dr. Frankenstein type stuff and stitch those disabled debug functions back into the Windows port using decompiled Linux port code as reference. It’d be really hard though. But probably worth it.

I got Raz’s helmet working, turns out it’s some hardcoded engine side stuff. A function exists called AttachKnapsackToPlayer which, despite specifying the player, takes an argument that will fix up the helmet and backpack for any entity using Raz’s model. Interesting. See, this is why we need docs!