Scripting documentation improvements

After scripting in Sansar for a couple of hours, here's some improvements that could help new developers get up-to-speed quickly.


The developer experience for the documentation could be improved with some minor changes. Being able to visualize the entire dependency tree is a quick way for developers to understand the breadth and depth of the API (e.g. /Sansar/Client/ScriptApi/access.html). Clearly denoting important classes in this tree would help a lot as well (e.g. ObjectPrivate and RigidBodyComponent) - same for functions/properties if you're able to include these in the navigation (e.g. StartCoroutine and Position).

Also, being able to search the entire API quickly (auto-suggest, no page reloads) would save a lot of time when developers are still a little unsure about where things live or even what their exact names are. You might be able to add/augment some existing documentation generator for both of these.

List of events

Of the various *.Subscribe() methods, the only event I know of is "src_fire_event", and that's because it's used in the CannonGameExample.cs. Listing the various event names and their use is pretty essential for doing anything more than extremely basic scripts.

Explanation of coordinates (physics)

With the long development feedback loop, it takes some time to understand object orientations when applying physics. I've started small and attempted to move a cube forward for 1 second, stop for 1 second, then repeat using SetLinearVelocity. What I experience is an object that just continuously goes off in a random direction until it hits a wall, then goes in another direction. I still haven't determined what X, Y, and Z refer to in the context of SetLinearVelocity - explaining this in documentation could save a lot of pain.

Object manipulation (more documentation)

Again, due to the long feedback loop, testing objects is painful. A brief tutorial on building CLI/console interfaces for objects (e.g. "/tell myobject stop") would allow much of the feedback loop to be short-circuited - developers can build simple commands to assist their debugging/testing in the simulator.

1 comment

Please sign in to leave a comment.