Using the client

Getting the original WorldsPlayer running, connected, and doing things. This is the guide for the stock client — if you want the modified one, read this first anyway, because everything here still applies.

Read Trust & safety before you connect anywhere. An unmodified client will run code that any server hands it, and your password travels in clear text. Both are five-minute reads and both change what you do next.

1. What you are actually installing

The WorldsPlayer is a Java program with a native 3D engine bolted underneath it. That one fact decides everything about installing it:

It needs a 32-bit Windows JVM. Not 64-bit, not a Linux one. The renderer is a set of 32-bit Windows DLLs and Java loads them through JNI.
On Linux that means Wine with a 32-bit JRE inside it. There is no port and there cannot be one without rewriting the renderer.
WorldsPlayer.exe is only a launcher, 87 KB. It finds the JVM and starts NET.worlds.console.Gamma. All the actual program is in lib/worlds.jar.

2. Installing on Linux

The path that works is Bottles with a jre6 bottle, which ships its own 32-bit runtime.

Make a bottle and install jre6 into it as a dependency.
Install the WorldsPlayer inside that bottle.
Run WorldsPlayer.exe from it.

The "JRE not found" dialog is usually a lie. It also appears when the client cannot read its own WorldsPlayer.ini — for example when the installation sits on Wine's Z: drive and the prefix is configured to refuse access to it. Put the installation inside drive_c and the message goes away.

Check which binary is running. It is easy to end up with two WorldsPlayer installations in one bottle registered under the same name, at which point which one starts is undefined and you will configure one while testing the other. That is worth hours of your life:

ps -eo pid,args | grep -i worldsplayer

3. The two configuration files

Almost everything is set in two .ini files beside the client, and they are the difference between "it works" and a week of confusion.

Copy them before you touch them. cp worlds.ini worlds.ini.original and the same for override.ini. Restoring those two files returns you to the starting state.

They are CRLF files. A plain sed edit leaves the line without its carriage return and mixes line endings inside one file. The .ini reader is native code and there is no promise it tolerates that. Put the \r back if you edit them from a script.

Which server the client connects to

This is the counter-intuitive one, and it is the single most common thing people get wrong.

There is no "server" setting. Every .world file has its own world server URL baked into it. What the configuration does is substitute that URL — and only under one condition.

The condition is that the world's own URL starts with worldserver://www.3dcd.com. If it does, the client swaps in your address. If it does not, the world tries its original host and you go nowhere.

The setting lives in override.ini, section [Runtime]:

[Runtime]
WorldServer=worldserver://127.0.0.1:6650

The port is mandatory. The substitution checks for a : after worldserver://, and without one the original port is not stripped correctly.

worlds.ini's WorldServer key is not read by the Java code at all. Different section, different reader. Set it for consistency if you like, but the effective one is in override.ini.

In a full installation of 557 worlds, 504 of them — 90%, GroundZero included — point at your server after that one edit. The remaining 53 have other hosts baked in and need their files patched.

The settings that matter

Setting	File	What it does
`WorldServer=`	`override.ini` [Runtime]	The server, as above. The one that counts.
`nocreateaccount=1`	`override.ini`	Sends the login dialog straight to "type a nickname" instead of the longer account-creation flow.
`RestartAt=`	`worlds.ini`	Where you reappear at startup. Format: `home:<dir>/<file>.world#<Room>@x,y,z,dir,…`
`upgradeServer=`	`worlds.ini`	Where worlds, avatars and textures are downloaded from.
`ScriptServer=`	`override.ini` [Runtime]	Where the permitted-avatar list comes from. Get this wrong and every custom avatar becomes the default figure — see below.
`useNetworkAvatars=1`	`worlds.ini`	Makes `avatar:name.mov` resolve against the upgrade server. Set it to `0` and it uses the local `avatars/` folder instead, and you need no HTTP server at all.
`VIP=1`	`worlds.ini`	Needed for `VIPAVATAR` to be read at all. The server also has to grant it.
`MULTIRUN=1`	`worlds.ini`	Two instances at once. Essential for checking that two users can see each other.
`DisableShaper=0`	`worlds.ini`	Turns on the built-in world editor. Guide.
`NetCacheModifiedCheck=0`	`worlds.ini`	See the warning below. Set this while you are changing content.
`debug=2048`	`worlds.ini`	Writes every received packet in hex to `Gamma.Log`. The best debugging tool the client has.

The client caches downloads for 72 hours by default. Change a world or a texture and it will keep using its three-day-old copy without asking. This is the single most common reason a change "does not work". Set NetCacheModifiedCheck=0 and clear cachedir/ whenever content changes.

4. Getting in

The WorldsPlayer login dialog — **The login dialog.** A name and a password, and on most servers the account is created the first time you use it. Remember that the password crosses the network in clear text — use one you use nowhere else.

Start the client. The login dialog asks for a name and a password. On most servers, including the ones in this project, the account is created the first time you log in.

Use a password you use nowhere else. It goes over the wire in clear text. See Trust & safety.

If it connects and then immediately drops, the most likely causes in order are: the world you started in has a different host baked in, the port is missing from override.ini, or the server is not actually running. Turn on debug=2048 and read Gamma.Log — it tells you which.

5. Moving and talking

Thing	How
Move	Arrow keys, or drag in the 3D view. Movement is sent to the server continuously; everyone in range sees it.
Say something	Type in the chat box and press enter. Everyone in the room sees it.
Whisper	Pick a person and whisper. It is routed through the server, not peer to peer — the operator can read it.
Emotes and actions	Defined in `actions.dat` beside the client. This is a data file, so the set of gestures is editable.
Buddy list	Add people and the server tells you when they come online.
Travel	Worlds are files. Open a world URL, or use the bookmarks in `gamma.worldsmarks`.

The client does not show you your own public chat. The server has to echo it back. If you type and see nothing while others see you fine, the server is not echoing — that is a server bug, not yours.

6. Avatars, and the failure that confuses everyone

Your avatar is set in File → Console Properties, in the Avatar (URL) field. It can be a built-in (avatar:willy.mov), a local file, or a URL on any web host. Making your own is a separate guide.

If everybody in the room — you included — turns into the same default figure, it is almost never a broken avatar.

The client filters avatars against a permitted-avatar list it fetches from the script server. When that fetch fails, it silently replaces every avatar that is not a plain .mov with the default one. A single 404 on that list is the reason "third-party avatars don't work".

Fix: make sure ScriptServer= points somewhere that answers. In the modified client, the Tools → Avatars button reads that state and tells you in a sentence.

7. World addresses

Worth understanding, because it explains how the whole thing hangs together:

http://host/path/kowloon.world#killingfloor@3021.0,346.0,150.0,296.0,0.0,0.0,-1.0
└──────── the file ────────┘└─ room ─┘└──────── where to stand ────────┘

A file fetched over ordinary HTTP, a room name after the #, then position and facing. Worlds are just files somebody put on a web server, which is why they survive on mirrors and why you can host your own.

8. When something is wrong

Symptom	Look at
"JRE not found"	Whether the client can read its own directory. Usually a `Z:` drive problem, not a missing JRE.
Connects then drops	`override.ini`: is the port there? Is the world one of the 90% that gets redirected?
Content changes do nothing	`NetCacheModifiedCheck`. Clear `cachedir/`.
Everyone is the default avatar	`ScriptServer`. See above.
Remote avatars freeze or fly off	The server is sending a bad update interval. The modified client guards against it.
Anything else	`debug=2048` and read `Gamma.Log`. It logs every packet in hex.

Two startup flags are worth knowing about: -esa turns the client's assertions on, so a malformed packet fails loudly instead of silently, and -Xint turns the JIT off, which makes it slow but deterministic. Both are in WorldsPlayer.ini.