[Opensim-dev] Protocol documentation, anyone?

[Hurliman, John]

> -----Original Message-----
> From: opensim-dev-bounces at lists.berlios.de [mailto:opensim-dev- 
> bounces at lists.berlios.de] On Behalf Of Cristina Videira Lopes
> Sent: Tuesday, December 09, 2008 2:55 PM
> To: opensim-dev at lists.berlios.de
> Subject: [Opensim-dev] Protocol documentation, anyone?
> 
> It's clear that we don't know a lot of things of the client-server
> protocol with the LL viewer. The fact that things like TPs and crossings
> kind of work seems to be entirely due to the relentless work of
> trial-and-error of some early contributors to OpenSim. Kudos to them!
> The fact that no one was even aware of EnableAgentCommunication is an
> indicator that this has been really, truly a case of honest reverse-
> engineering... The current state of things is extremely fragile, though.
> If we try to fix some oddity in one corner of the protocol, chances are
> we are going to screw up seven different things in the rest of the
> protocol, because we don't know what the client wants.
> 
> So -- we need help. Calling for people who don't see themselves
> contributing code to OpenSim core, but that want to help its
> development by helping make the guessing game less painful!
> 
> The challenge is to read the LL viewer source code and try to get an
> understanding of what the client expects from the servers with respect
> to region crossings and teleports. Here are some examples of things I
> would like to know:
> 
> - How are seed capabilities being used in the client? - Do all child
> agents have their own seed cap, or do they share that seed with the root
> agent? - Does the client care about who sends it seed capabilities? -
> What is the expectation on the seed cap that is sent on
> EstablishAgentCommunication, CrossRegion, FinishTeleport? - Do child
> agents have Event Queues? If so, when are they opened/closed? - Under
> what circumstances does the client close or refuse to use an Event
> Queue? ...
> 
> If anyone is interested in doing this important piece of work, I have
> very concrete viewer log messages that can serve as starting points
> for mining the client code. Just let me know!
> 
> Thanks,
> Crista
> 

There's always the route of reverse engineering the communications (which has worked well in the past). I know no one likes to work on things that aren't directly fixing bugs or adding features to OpenSim core, but the indirect benefits are huge of having a robust set of tools for reverse engineering these things. The EstablishAgentCommunication issue would have been discovered much earlier if logs were made of capabilities requests and EventQueue communication for every viewer release.

The viewer is also a fairly good debugging tool itself. If you get ahold of a copy compiled in RelWithDebugInfo mode, it will dump lots of good information to the console while it runs. Watching the SecondLife.log in real-time or going back after something went wrong can sometimes give hints.

I bring it up because this thread looks exactly like what the libomv team went through about six months into the project. Everyone shouted for help, attended lots of in-world meetings, participated on sldev, and tried to start documentation efforts, without much success. Anything that came out of it is scattered across http://wiki.secondlife.com/wiki/, but we only made real progress by improving GridProxy and working with dedicated reverse engineers.

John