Whether closed source or open source, development systems live and die by their documentation. Documentation is the unwanted stepchild of many development efforts; developers tend to focus on getting code written rather than on explaining the code that's already there. The problem is amplified; poorly-documented code tends to get modified in ways that make it even harder to document or understand.
The Second Life team maintains a public wiki for documentation. This project, while incomplete (all documentation is incomplete) is actively maintained and updated. The wiki documents both the in-game scripting language and the architecture of the C++ source. The scripting language (LSL) is fairly well documented, although some sections are incomplete. For instance, the Communications category lists three subcategories; Chat, HTTP, and XML-RPC. Only the Chat category has been completed. In general, if a link on the wiki page is red, the material hasn't been written yet. The link serves as a placeholder to show that there is something there to be documented.
It's not unusual for any product to have incomplete documentation. I've seen dozens of commercial manuals with a page or two of "Gzornenplatz setting (Enabled/Disabled): Enable or disable gzornenplatz." Never a hint of what a gzornenplatz is, or what effect enabling it has. What makes the Second Life documentation interesting, and ties in well with the open source release of the viewer, is that the wiki is editable by users and encourages contributions. While hardly rare in an open-source project, this is very unusual for a commercial project. It's even more unusual for a wiki to be the primary documentation; they are more often used for supplemental material. This offers some advantages and some disadvantages; it'd be nice to have more complete documentation already provided, but the ability to edit the documentation means that this will probably get addressed soon. If it's not a good thing already, it will be in a few months.
It's not unheard of for companies to treat their protocol as a trade secret. Some publishers of online games have put a fair amount of work into legal defenses of their protocols. The Linden Lab approach appears to be to focus on a secure protocol such that untrusted clients are not a threat, and publish everything. As a developer, of course, I like this a lot.
There has always been some essential ambiguity about the potential for keeping a protocol completely secret while trying to get millions of people to run it on computers completely under their control. Simply releasing the documentation defuses the issue. Of course, this works partially because Second Life isn't primarily a "game" in the conventional sense. World of Warcraft players have been known to complain at great length about people using bots to control their characters, because this can give people unfair advantages in a game that has competitive aspects. There have been issues with Second Life being abused (CopyBot being one of the most famous; see Resources), but in general, without a competitive system, and with the server able to provide most of the needed security, it's not been as much of a problem. In a world where everyone can teleport or fly, there's no concern about users using "speed hacks" to outrun other users.
Access to source creates a third category of documentation. The LSL documentation is useful even to someone who's never going to touch a C++ compiler or a line of source and who just uses prebuilt downloads of the viewer. You can use the LSL documentation to write scripts for objects, and just build objects in the simulator using the standard client. No problem. The conventional developer documentation (of which there is quite a bit) explores the C++ architecture. With this documentation, you can more easily modify the source and add features to the existing code. The third category is protocol documentation, documenting the communications with the server, not just the internals of the client. Given protocol documentation and a whole lot of free time, you could in theory write an entirely new implementation that would communicate with the server. In fact, people have done some work on exactly this, without the benefit of the wiki; the libsecondlife project (see Resources) was built on reverse-engineering at first.
If you want to modify the Second Life client, the architectural guidelines and detailed documentation of everything may not be the most approachable starting point. They're excellent if you want to do a lot of things, but if you just want to do one thing, it's a lot of reading. The wiki now has a few "learn by example" pieces up that walk through a particular task (see Resources for a link). In the likely event that your proposed modification is similar to one of these, or at least includes one of the tasks covered, these give a quick overview of what to do and where to do it.
The documentation release and the source release complement each other; if something isn't documented, you can read the source. If the source is hard to follow, the documentation may help explain it. Making both source and documentation available makes each one more useful.
If you're trying to get your head around the whole system, the best starting point may well be the Glossary (see Resources). Once you're familiar with the terminology, the "Viewer source" page (linked in Resources) gives a good list of its components, giving high level functional descriptions, such as explaining that "llmath" is a basic 3D math library. Like any reasonably well-linked wiki, the documentation encourages browsing.
Using the documentation to explore the code
The documentation gives us a starting place for finding things in the source code. If you want to add a feature to the Second Life viewer, or modify an existing feature, you'll have to find where in the code to start typing. So, how would you go about this? The obvious starting place is the "Learn by Example" section of the Viewer architecture page (see Resources). While incomplete as of this writing, this section gives simple summaries of the steps used to perform common tasks, such as adding a menu item.
The menu item example is a good one. The code example given is quite short. The article quickly runs through the XML files used, where to find them, what to put in them, and the minimal code for an event handler for a menu item. With three code segments (one XML, two C++) and a few short bits of explanatory text, you are exposed to the XML structure used to describe the API, the C++ API for event handlers, and the way event handlers are registered.
The XML is straightforward:
Listing 1. XML for a menu item
<menu_item_call label="Foo" enabled="true" name="foo_menu">
<on_click function="Tools.Foo" userdata="" />
</menu_item_call>
|
The event handler is only mildly more complicated:
Listing 2. An event handler
class LLToolsFoo : public view_listener_t
{
bool handleEvent(LLPointer<LLEvent> event, const LLSD& userdata)
{
llinfos << "foo!" << llendl;
return true;
}
};
|
This is a good example of where you might want to do more detailed reading. The example code for adding a menu item refers to an object of type "LLSD". What's that? The page refers to it as a structured data type similar to variables in Python or Perl. A quick entry in the wiki's search box yields a page giving concrete details on how LLSD objects hold values, ranging from scalars to arrays and maps, and talks about serialization and conversion operations. or maps, capable of convenient serialization and conversion. In context, an LLSD object is used to pass in any additional data specified in the XML file defining a menu item. While reading this, I spotted a couple of typos. I fixed them. I think this, more than anything else, defines what makes the open source release of the viewer interesting; it's not a gimmick, but rather, part of a general practice of involving the user community.
Listing 3. Sample code to register the event handler
(new LLToolsFoo())->registerListener(gMenuHolder, "Tools.Foo");
|
The documentation could go into more detail on some of this; for instance, you
might want to know more about the registerListener
function, apparently inherited from view_listener_t.
However, the example gives you enough information to start with. The first
argument is the object that holds the menu; the second argument is the menu
object's name, taken from the XML. If you need to know more, the code is provided;
what the documentation has done is tell you where to start looking. In a source
directory with many megabytes of code, just knowing that menu items are registered
in the initialize_menu_actions() function in
newview/llviewermenu.cpp saves plenty of time.
Many articles give high-level overviews of a given section of code, rather than detailed descriptions of algorithms and code. That makes sense; if you want to find out exactly what each line of code does, the best thing to do is read the code. So, the page describing the image system gives a high level overview discussing how the system prioritizes which textures to fetch; it does not give the exact algorithm, but rather, explains the inputs to that algorithm in general terms.
One other useful tidbit from the example code is the "llinfos" stream. This is a way to display error messages or diagnostics; the code has a number of examples of diagnostic messages sent to this stream, many of them commented out in the release. These messages show up in the window you ran the viewer from, if you started it from a command line. A release client might wish to suppress some or all of these messages, but for debugging, it's ideal. If you're looking to figure out what's going on, the llinfos stream is your friend.
You still need a server to connect to. If you want to run the client locally without a network feed, this is a problem; while the client has been released as open source, the server hasn't. There's a project to build a compatible server, which is not really comparable yet to the official server project, but might be enough for a bit of recreational debugging. It's called OpenSim (see Resources for a link).
Something that fascinated me when I first saw it in the 80s was a BBS with a feature where posts in all-capital letters would be automatically translated into lowercase, or even an approximation of correct case. Interestingly, this has a huge effect on perception of a user's competence or intelligence, even though it's a purely mechanical translation. I can hardly imagine the effects you'd get by removing the word "lol" whenever it's used to end a sentence. Talking about this led to the question of whether it would be practical to add a simple and transparent language translator to the Second Life client. It is! In my final installment, I'll show how to plug a simple translation protocol into the Second Life code. As the chat mechanism is only lightly covered in the documentation, it's a good starting point for further code exploration.
Learn
- Read
more Second Life articles
on developerWorks.
-
CopyBot can copy some things
that are tagged "not for copying."
- The Viewer Architecture page has
a
section for learning by example.
- This page gives
a
simple overview of the components of the Second Life viewer.
- Having seen
the
excellent Second Life glossary,
I can't understand why other computer documentation doesn't always contain a
glossary.
-
Libsecondlife, a
third-party library
launched in May 2006 and
providing tools that are intended to be compatible with the official release, also
has a quite useful wiki.
- There is also work being done on
a free and open source
server compatible with Second Life clients.
At the time of this writing it is marginally functional.
- In the
developerWorks
Linux zone,
find more resources for Linux developers.
- Stay current with
developerWorks
technical events and Webcasts.
Get products and technologies
-
Order
the SEK for Linux,
a two-DVD set containing the latest IBM trial software for Linux from DB2®,
Lotus®, Rational®, Tivoli®, and WebSphere®.
- With
IBM
trial software,
available for download directly from developerWorks, build your next development
project on Linux.
Discuss
- Check out
developerWorks blogs and
get involved in the
developerWorks
community.
Comments (Undergoing maintenance)
Table of contents
Local resources
My developerWorks community
Tags
Use the slider bar to see more or fewer tags.
Popular tags shows the top tags for this particular content zone (for example, Java technology, Linux, WebSphere).
My tags shows your tags for this particular content zone (for example, Java technology, Linux, WebSphere).
Popular article tags |
My article tagsSkip to tags list
Popular article tags |
My article tags
