Neighbourhood Snapshot

Introduction

This application is designed to help those unfortunate avatars who have (often by default) taken on the onerous task of being the "Mayor" of a PortaZone community in There.

When you run the application, it dumps a snapshot of the state of all PortaZones visible in your vicinity. The dump includes information such as the position and ownership of the zones, as well as letting you know how long they have before they will run out of time. Any zones that are close to running out of time are flagged at the end of the output so that their owners can be informed.

Running this application requires you to install a recent Java Runtime Environment (JRE) and operate your There client in debug mode. If you're not happy with either of those, please don't download or install this application.

Preparation

First thing to do is make sure you have a recent enough version of the Java runtime. I am using 1.4.2_02 for development, so that would be ideal, but any 1.4.x should be sufficient. 1.3.x JREs and the Microsoft JRE are not sufficient to run this application.

To find out which version of the JRE you have, open a command prompt window. If you can find this in the Windows menus, that's great; otherwise, type Windows+R then type "command" in the field provided. In the command prompt window, type "java -version". The result on my machine looks like this:

java version "1.4.2_02"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.2_02-b03)
Java HotSpot(TM) Client VM (build 1.4.2_02-b03, mixed mode)

If you don't have a decent runtime, go to http://www.java.com/ and press the "get it now" button. Re-check the version once that has downloaded (you may need to close the command window and open a new one).

Installation

Download this zip file and unpack it into a directory somewhere on your machine, say C:\snapshot. You will find that it contains a whole stack of .jar files, most of which are libraries of code that I use. The application itself is contained in snapshot.jar.

Flip back to the command prompt window and use the CD command to get into the same directory with the .jar files. Then type this:

java -jar snapshot.jar

The application should respond that you need to include a password. If it doesn't, something is broken. Don't give it your password yet.

Running

Start your There client, and go wherever you want to take the snapshot. If your neighbourhood covers a large area, it is good to stand in the middle somewhere.  Wait until the portazones in the area have all appeared: the application can't always see invisible ones. Start debug mode using Ctrl+Shift+L.

Switch back to your command prompt window and type this:

java -jar snapshot.jar password

Enter your own There password there, of course. You don't need to enter your avatar name, because the first thing the application does is ask the client for that. You should see that it is getting along with that when you see the following text appear:

Logged in to client.
Pilot: 196772622 = iay

Of course, you will see your own avatar name and doid there, not mine. The "Logged in to client" implies that the application was able to talk to the client. If you get a connection error instead, you probably didn't start debug mode properly. In this case just flick back to the client and type Ctrl+Shift+L and try again.

The next step in the application is to log into the There web services. You will see something like the following if all goes well:

Logged in to There.

The application will now serve up a stack of information for you that we can cover in detail later. It will also drop a copy of this into a file, and tell you where it is so that you can look at it later:

Output file is: C:\Documents and Settings\iay\S7-20040226180643.txt

The file is placed in an odd location for reasons that are too dull to go into; the file name is made up from the sector number and the date and time in UTC.

Also in that directory you will find a file called avatar-names.txt, which is a cache of recently seen avatar name translations from doids. You will find that as the application learns peoples' doids, it runs much faster in the future.

Interpreting Output

The initial output for the application will normally look like this:

Logged in to client.
Pilot: 196772622 = iay
Logged in to There.
Output file is: C:\Documents and Settings\iay\S7-20040507153049.txt
Snapshot time: 07 May 2004 15:30:49 UTC (local: 07 May 2004 16:30:49 BST)
Pilot iay at (757.972041,3085.688971,6000167.108173) in sector 7
Portazones visible: 14

The first four lines of this output have been described above. The "snapshot time" should be the current time, expressed both as the time in your real-world location and as UTC ("Universal Coordinated Time", which is more or less another name for GMT). The UTC version of the time is included in case you want to show the output to someone from There engineering; There's servers (like most others) run on UTC internally.

The "pilot" line should include your avatar name and your precise in-world location.

Typical output for a healthy PortaZone is as follows:

Paz doid=332765953 ssot=7 pos=(561.483666,3549.267317,6000183.288845) (503m)
   Large Portazone owner=206750542 (Terrapin)
   paid=32544228502 (17 May 2004 15:26:56 UTC)
      left=9 days 23 hours 56 minutes

The portazone described here has a doid (Distributed Object IDentifier) of 332765953. It is located in sector 7, at exact co-ordinates (561.483666, 3549.267317, 6000183.288845). This is 503m from your current position.

This is a large portazone owned by the avatar Terrapin. If the avatar's name is not shown, this is usually because their profile is private, or they have you on ignore.

The portazone has enough charge on it to remain in-world until simulation step 32544228502, which is equivalent to 17 May 2004 15:26:56 UTC. This is 9 days, 23 hours and 56 minutes from the time you made the snapshot.

If some of the visible portazones were not casual portazones (limited to four hours in any case) and had less than 36 hours time remaining, you might see something like this at the end of the listing:

Portazones expiring soon: 2
   Paz doid=253035492 owner=iay
   Paz doid=305473035 owner=iay

It might make sense to check the amounts of time left on these zones in the main listing and inform the owner that their zone is close to expiry.

Really Big Villages

If your community contains more than about 18 PortaZones, or has been accidentally placed across a boundary between two sectors in There, you may find that the snapshot application does not show all of the community in a single run. This is due to the algorithm used by There's visibility servers, which try to reduce the load on your client program and internet connection by only making a limited number of each class of objects (PortaZones, avatars, dogs, etc.) visible to you at any given time no matter how many are really in the area.

The first suggestion in this case is to check that your village doesn't straddle a sector boundary; as well as confusing this application, you will probably see other strange effects on a day to day basis that you won't like. You can see where the sector boundaries are by enabling QuintanaVision in your There client program. Alternatively, look at the ssot values in the snapshot application output; if more than one value is in use in your village, you probably have a problem.

If the problem is not due to multiple sectors, the best thing to do is to find two (or more!) locations in your village from which you can run the application, and run it more than once to check the status of the PortaZones.

Other Random Hints

Don't build your village in either sector 1 or sector 73. Both of these "open ocean" sectors have a single server covering huge geographical areas (in the case of sector 1, almost the whole of the planet) and There, Inc. don't guarantee sensible behaviour "out there". Building on the ocean close in to the main islands is a different matter. Use the snapshot application or the hostHud facility to find out which sector you are in.

The application doesn't know which PortaZones you care about and which you don't. This means that if someone places a zone "near" your village, it may appear in the listing. Depending on conditions, you may be able to see PortaZones up to 1km from your current location.