Directory structure

Almost all source code is located in the solipsis directory and its descendents:

• lib: external code used by Solipsis and gathered here for convenience
• navigator: various navigator implementations
  • navigator/wxclient: main graphical navigator
  • navigator/netclient: experimental text-mode navigator (not up-to-date)
• node: the node implementation
• services: basic service handling code
  • services/*: one subdirectory per installed plugin
• util: common subroutines and classes

The lib directory

Contains some external Python libraries used by Solipsis, when they are not properly packaged by most Linux distributions.

• stun.py: the STUN implementation from shtoom (http://shtoom.divmod.org/)
• simpletal: the simpleTAL (http://www.owlfish.com/software/simpleTAL/) library, a simple template library

The util directory

Many useful functions and classes.

• address.py: the Address class represents a Solipsis address (currently an UDP host/port pair)
• autohash.py: Autohash is a metaclass to enable hash calculation on instances given a list of attributes used to calculate the hash
• bidict.py: bidict is a bi-directional dictionnary; helps having a mapping and its reverse in the same structure
• entity.py: Entity is the basic class for all Solipsis entities (i.e. nodes)
• exception.py: Solipsis-specific exceptions (nearly unused)
• httpproxy.py: a function to discover system-wide HTTP proxy configuration, and a class to enable XMLRPC connections via an HTTP proxy with Twisted
• launch.py: the Launcher class can launch a Solipsis node in a separate process, in a cross-platform way
• marshal.py: the Marshallable mixin defines the FromStruct and ToStruct methods so that objects can be mashalled over XMLRPC; these methods can be overriden for specific behaviour
• memdebug.py: a simple class used to track object creation and deletion in a Python program
• nodeproxy.py: encapsulates basic connection stuff (e.g. XMLRPC) so that a remote node can be talked to transparently via a proxy object
• parameter.py: parsing of Solipsis config values from an .ini-style file
• position.py: Position is the object representation of a 3-coordinate position
• remote.py: high-level encapsulation of the connection to a remote node (should be preferred to nodeproxy.py)
• singleton.py: generic singleton class builder
• timer.py: small classes that ease calculation of values evolving with time
• uiproxy.py: two mixins that make very easy to communicate between the Twisted event loop and the wxWidgets event loop
• urlhandlers.py: cross-platform registering of URL handlers (so that URLs beginning with e.g. "slp://" are clickable in a browser)
• urls.py: SolipsisURL encapsulates a Solipsis URL and gives methods to parse and extract components of URLs
• utils.py: various useful functions and classes
• wxutils.py: various wxWidgets-specific functions and classes

The node directory

This is the node implementation. It is usually launched via the twistednode.py script at the base directory.

• bootstrap.py takes the user's parameters and launches the requested number of nodes with the desired characteristics
• control.py: the RemoteControl object receives remote commands and processes them (e.g. sent through XMLRPC)
• delayedcaller.py: DelayedCaller is a convenience class to handle delayed calls with Twisted
• main.py is the main routine, it parses command-line arguments and handles control over to the bootstrap routines
• node.py: derived from Entity, the Node class representes our local node (as opposed to our peers)
• nodeconnector.py: NodeConnector is the class used to send and receive Solipsis messages through the Twisted API
• peer.py: derived from Entity, the Peer class represents one of our peers (e.g. other nodes in the network, as opposed to the Node class)
• protocol.py: the Parser class is responsible for parsing and building Solipsis messages to/from a simple object representation
• statemachine.py: the StateMachine class is the heart of the Solipsis node, it receives messages and commands, reacts to them, updates the internal state and sends other messages or notifications
• states.py: the various states recognized by the state machine
• topology.py: the Topology class gathers our peers and handles all geometric calculations useful for the Solipsis algorithms

The navigator/wxclient directory

This is the wxWidgets (http://www.wxpython.org)-based navigator implementation. It is our only graphical client at the moment. There are three types of files here, as most UI elements are designed using wxGlade (http://wxglade.sourceforge.net/):

• lowercase.py files are regular hand-written Python code files
• CamelCase.py files are Python files generated by wxGlade, also including some hand-written code (for handling UI events and the like)
• navigator_gui.wxg is the wxGlade file containing specification of frames, windows and widgets

Here is a more detailed description:

• app.py contains the main application class (derived from wx.App); it handles all initialization procedures as well as the handling of all events for the main window (which is not generated with wxGlade currently)
• bookmarks.py: the Bookmarks class is a list of bookmarked peers; it is normally stored inside the ConfigData class
• config.py: the ConfigData class is able to persistently store configuration values; it can also manage several identities and switch between them at will
• drawable.py: some classes to draw different types of graphical objects (text, images) in a wxWindow
• images.py: handles loading of some Solipsis images and icons
• jumpposition.py: the JumpPosition class is able to store a position the user wants to jump to
• main.py: parses command-line options and launches the graphical application accordingly
• network.py: Network is the main class launching the Twisted event-loop (in a separate thread). It also includes very basic remote node management: connection, disconnection and killing of the node.
• statusbar.py: StatusBar stores and displays text in the main window's status bar
• urllistener.py: two classes based on the Twisted API and able to listen to receive instructions from external programs, so that we can jump to a Solipsis URL from e.g. a Web browser
• validators.py: various validators to check data entered in forms of the graphical interface, designed so as to interface with the wxWidgets Validator API
• viewport.py: the Viewport class handles drawing of the Solipsis world as currently seen by the node
• world.py: the World class contains the Solipsis world (peers, pseudos, avatars...) as currently seen by the node