Platform Tutorial Getting Started

From Multiverse

Overview

This part of the tutorial walks you through setting up a Multiverse development environment, including the servers, the Multiverse Client, and the tools. It does not cover any issues related to game design; see MMOG Design for more information on designing a massively-multiplayer online game.

For development the suggested platform is Windows XP, because you can run the tools, server, and client on the same machine.

For deployment, run the servers on Linux for speed and economy. For information on installing the server on Linux, see Rapid Linux server setup guide.

See Updating the Server for notes on installing a new server installation.

Hardware requirements

For a single-machine development environment, the hardware must be able to run both the Multiverse Client, tools, and server suite. The requirements are:

• Operating System: Windows XP SP2 or Windows XP Professional x64 Edition.
• Processor: Pentium 4; 2.5GHz or greater
• RAM: 1GB or more
• Video: DirectX 9-compatible video card. Pixel shader 2.0 and vertex shader compatible hardware with 128 MB of texture memory. See Supported Graphics Cards for more information.
• Audio: DirectSound-compatible sound card.

NOTE: Be sure your video card is on the list of Supported Graphics Cards; not having a sufficiently powerful graphics card is the most common source of problems running the Multiverse Client.

Download

Download the client, tools, and server.

• Download Multiverse client - user registration required.
• Download Multiverse tools and server - developer registration required.

Install tools and client

Installing the tools and the client are easy, because they have Windows installers. Just run the .exe file you downloaded. Once you install the client, it will automatically update itself each time you start it.

Run client and access Multiverse Demo World

Demo World

NOTE: If you've previously used the Multiverse client to enter the Demo World, you can skip this step.

Start the Multiverse client by double-clicking on the icon. First, you will see the Multiverse Network login screen: Enter the user name and password you specified when you registered the client (NOT the developer login for the Multiverse tools and server).

You will then see the Demo World splash screen and after a brief pause, you will enter the Multiverse Demo World. Initially, the client will display a help dialog box; after you close the dialog box, you can start to move around in Demo World. For more information on the user interface, see Using the Multiverse client in Demo World.

Connecting from behind a firewall

If you are connecting to the demo worlds from behind a firewall, you must ensure that the following ports are open:

• TCP ports 9005 and 5040
• UDP ports 9010 and 5050

You may need to contact your network administrator to enable access on these ports.

Troubleshooting

If you encounter problems, see Client Troubleshooting for some suggestions.

Download and designate asset repository

When you first start Model Viewer (or any of the Multiverse tools), a dialog box will open prompting you to download and designate an asset repository.

Designate an Asset Repository dialog box

Follow these steps:

1. Open Model Viewer.
2. A dialog box will appear that tells you to download or designate an asset repository. Click "Download a new Asset Repository". This will open a web page with links to the two prebuilt asset repositories.
3. Download the Complete Asset Repository (56 MB) that contains all the assets required by sampleworld, plus some other assets.
4. Unzip the asset repository to any directory. This is your asset repository directory.
5. Click "Designate an existing Asset Repository", browse to the asset repository directory, and click Continue. The "Complete Asset Repository" will be in a folder called "Sample Asset". This is the asset repository that all the Multiverse tools will use. You can also make the Multiverse Client use this asset repository with the --use_default_repository (or --development) option.

View sample assets

Zombie mesh in Model Viewer

You can now start to use Model Viewer.

1. Choose File | Load Model, and browse to the Meshes sub-directory of your asset repository directory.
2. Select a model (mesh file) to load. A good example model is the zombie (the last mesh file listed, since they are shown in alphabetical order).

You will see the model in Model Viewer.

From now on Model Viewer, and any of the other Multiverse tools will use the asset repository you just designated. You can always change it by choosing File | Designate Asset Repository in any of the tools.

If you like, use Model Viewer and look at some of other the sample 3D art assets.

Choose File | Load Model to open 3D models available in the asset repository that are free for your use.

Try out World Editor

Sampleworld in World Editor

Before you start installing the servers, which can be a lengthy process, check out the World Editor tool. This may require you to unzip the Multiverse Server .zip file you have downloaded, as the sampleworld.mvw file you will be looking at is contained in that file. Just unzip the file in a temporary directory for now.

1. Double-click on the desktop icon to start the tool.
2. Choose File | Load World.
3. Browse to mv_home/config/sampleworld/sampleworld.mvw, and click Open.

This is the world file for sampleworld, the basic sample provided with the servers.

For information on how to use World Editor, see Using World Editor.

Install the Multiverse servers

Installing the server suite is a little more complicated. These are the basic steps

1. Install prerequisite software:
   • Java Development Kit (JDK): Java enables servers to run on both Linux and Windows.
   • Database: MySQL and MySQL JDBC driver for database persistence.
   • Cygwin for Linux shell emulation on Windows (optional)
2. Extract server files
3. Modify the property file (optional, depending on your installation)
4. Configure database server
5. Start the servers and run sampleworld to verify your installation

Install prerequisite software

Before installing the server, install the following:

• JDK 5.0 - the J2SE Java Development Kit from Sun Microsystems. This page has several links. Choose the link "Download JDK 5.0 Update X" where X is the latest number. Don't download the Java EE SDK or NetBeans (unless you want to use the NetBeans IDE).
• MySQL 4.1+ database (essentials download). Use standard configuration. On Windows, accept the default application settings until you get to the install as service screen. Install as a service. Set up an account that can log in remotely with the following settings (if you change any of these settings, see "Configuring MySQL"):
  • Use 'Standard Configuration'
  • Install As Service
  • User name: root (this is already defaulted)
  • Password: test
  • Database name: multiverse (this information will be created when you run the install SQL script)

• MySQL Connector/J JDBC driver. Unzip this to C:/ (you can use any directory, but this will put the JAR file in C:\mysql-connector-java-3.1.xx\mysql-connector-java-3.1.xx-bin.jar, which is the default setting in the startup script). You actually only need the library mysql-connector-java-3.1.xx-bin.jar, so you can extract just that file, to save space, but it doesn't hurt to have all the extra files. NOTE: Do not put the JDBC driver in a directory path containing spaces.

• Cygwin Linux shell emulator (optional). If you install Cygwin, in addition to the default packages, install:
  • net.openssh
  • net.openssl
  • editors.vim (and any editor you want, such as emacs)
  • base.gzip
  • base.tar
  • interpreters.python.

In this tutorial (and the documentation in general), the directory where you install the server is referred to as mv_home.

Using Cygwin (optional)

Developer eavabfreelight created a video tutorial on Cygwin installation and basic functions. Check it out if you are new to Cygwin and/or Linux.

Cygwin is a Linux shell emulator that provides a Linux-like environment for Windows systems. It enables you to run Linux shell scripts (and other Linux commands) on a Windows system. For more information, see Using Cygwin.

Installing Cygwin is optional, but many developers find it useful because it provides a more powerful shell than the native Windows Command shell, along with many other useful features.

Cygwin installation automatically creates a /home/username directory, where username is your user name. The Windows path to this directory is C:\cygwin\home\username, if you installed to the default location.

When using the Cygwin shell, you can use either Windows style or Linux style directory paths:

• When using Linux style paths, the directory where Cygwin is installed (by default C:\cygwin) becomes the "root" of Linux style directory paths. The Windows C drive becomes the "c:" directory. Directory separators are forward slashes, and you must escape spaces in directory names with a backslash.
• When using Windows style directory paths, you must enclose directory paths in quotes, and then you can use backslash as the directory separator, and include spaces unescaped.

For example, the following two commands are equivalent:

• Linux-style:

cd Program\ Files/Multiverse\ Client/bin

• Windows-style:

cd "Program Files\Multiverse Client\bin"

CAUTION - Do not combine Linux-style paths and Windows-style paths in a single command or environment variable. Choose one style and stick to it.

Extract server files

The server files are provided in both a zip file and a gzipped tar file (tgz archive). You can extract the zip file with a graphical tool such as Winzip. To extract the tgz archive, open a Cygwin window, and enter these commands:

cd download_dir
tar zxf server_date_versionnumber.tgz

This will create a download_dir/multiverse directory, referred to here as mv_home. A good place to install the servers is c:\multiverse (so, copy the .tgz file to C: and run the above commands there), but you can install it anywhere you like.

NOTE: Do not install the Multiverse servers to a directory path containing spaces.

Modify property file

Initially, just use the default properties file provided with the servers, mv_home/bin/multiverse.properties. To change any of the default configuration properties, edit the Multiverse Property File.

When you want to create your own world, "best practice" is to copy multiverse.properties to your own file, for example, myworld.properties, which you can then customize as needed. You can then specify that property file on the command line as the first argument to the server start script.

JDBC driver JAR file

Set the path to your MySQL Connector/J JDBC driver driver JAR file in the following line:

multiverse.jdbcJarPath=c:\\mysql-connector-java-3.1.14\\mysql-connector-java-3.1.14-bin.jar

If your JDBC driver JAR file has this exact name and path, then you don't need to change anything. Otherwise, change it to match exactly where you installed the JAR file.

Database properties

If you did not use the suggested MySQL settings, edit your properties file and set the MySQL database name, username, password, and host name to match those you entered when you installed MySQL:

multiverse.db_name=multiverse
multiverse.db_user=root
multiverse.db_password=test

If you used the suggested settings when you installed MySQL, you can skip this step.

Set environment variables (optional)

Setting some environment variables is optional, but may be convenient:

• Set the DEFAULT_MV_PROPERTYFILE environment variable to the name of the default properties file in the mv_home/bin directory. If this environment variable is set, then scripts will use its value when you do not specify a properties file on the command line (otherwise, the default is mv_home/bin/multiverse.properties).
• On Linux, Set the MV_HOME environment variable if you want to run the server scripts from a directory other than mv_home. On Windows, you must run start-multiverse.bat from mv_home.
• Set ENABLE_MGMT to "true" to enable server management and monitoring. Otherwise, set it to "false" (the default). See Monitoring and Managing the Servers for more information. This is purely optional. Management and monitoring is a feature still under development.

For information on how to set environment variables, see Setting Environment Variables.

Configure database server

The current Multiverse server suite is configured to work with MySQL, an open-source database.

Because the database layer uses JDBC, it is completely portable to any major SQL-compliant database server. Support for other databases will be provided in future releases.

Set up the database

You must set up the database that the Multiverse servers use.

1. First, make sure the MySQL database is running; if not, start the database. Generally, MySQL will be running after you install it.
2. On the Start menu choose Programs | MySQL | MySQL Server 4.1 | MySQL Command Line Client. A window will open prompting you for the password. Then the MySQL Command Line Client will display this text:

   Welcome to the MySQL monitor.  Commands end with ; or \g.
   Your MySQL connection id is 4 to server version: 4.1.21-community-nt
   
   Type 'help;' or '\h' for help. Type '\c' to clear the buffer.
   
   mysql>
   

3. In the MySQL Client, enter the command:

   mysql> source mv_home/bin/install.sql
   

   For example, if mv_home is C:/multiverse, enter

   mysql> source C:/multiverse/bin/install.sql
   

On Linux (or in a Windows command shell window), if you have added MYSQL_HOME/bin to your PATH environment variable, you can run the file directly with these commands:

cd mv_home/bin
mysql --user=username --password=password < install.sql

Testing the database

To make sure the database was created properly, you can view the tables in the multiverse database as follows:

mysql> show tables from multiverse;

You should see a list of all the tables in the database:

+----------------------+
| Tables_in_multiverse |
+----------------------+
| namespaces           |
| objstore             |
| oid_manager          |
| player_character     |
+----------------------+
4 rows in set (0.00 sec)

Otherwise, the database is not working or created properly. Then, exit MySQL command line client:

mysql> exit

Start the servers

Configure or disable firewall

If you are running a local software firewall, temporarily turn it off. Although it is possible to connect to a server running a firewall, it is easier to simply turn it off. For more information, see Server Troubleshooting.

Starting the servers on Linux

This procedure also applies if you are using Cygwin on Windows.

IMPORTANT - Ubuntu Linux users read this:: Running the start scripts on Ubuntu.

Fedora Core 7 users, read this: Running Multiverse Servers on Fedora

To run sampleworld, follow these steps:

1. Open a command shell window.
2. Enter these commands, where mv_home represents the directory where you installed the Multiverse servers:

    cd ''mv_home''/bin
    ./multiverse.sh -v start
   

   You will see these messages:

   *** Starting world sampleworld ***
   Enabling JMX mgmt & monitoring
   MV_HOME is ..
   Using property file ../bin/multiverse.properties
   Using world file ../config/sampleworld/sampleworld.mvw
   Using world script directory ../config/sampleworld
   Using log directory ../logs/sampleworld
   Using common directory ../config/common, bin directory ../bin
   Dual World Manager Flag = 0
   JAVA_FLAGS="-Dcom.sun.management.jmxremote -cp ../other/rhino1_5R5/js.jar;c:/mys
   ql-jdbc/mysql-connector-java-3.1.14-production-bin.jar;../dist/lib/multiverse.ja
   r;../dist/lib/mars.jar;../other/java-getopt-1.0.11.jar;../other/jython_2_1.jar;.
   ./other/log4j-1.2.14.jar;. -Dmultiverse.propertyfile=../bin/multiverse.propertie
   s  -Dmultiverse.logs=../logs/sampleworld"
   Starting domain server:        SUCCESS
   Starting animation server:      SUCCESS
   Starting combat server:         SUCCESS
   Starting object manager:        SUCCESS
   Starting login manager:         SUCCESS
   Starting world manager 1:       SUCCESS
   Starting proxy server:          SUCCESS
   Starting world reader:          SUCCESS
   Starting mob server:            SUCCESS
   Wait for finished initializing msg...
   

When the servers are ready for you to log in, you will see this message:

DONE INITIALIZING, you can log in now

Starting the servers on Windows

Follow this procedure only if you did not install Cygwin.

1. Open a Windows Command Prompt window. Shortcuts are usually available in several places, for example Start > Programs > Accessories > Command Prompt.
2. Enter these commands, where mv_home represents the directory where you installed the Multiverse servers:

    cd mv_home/bin
    start-multiverse.bat
   

   You will see messages like this:

   DEFAULT_MV_PROPERTYFILE is multiverse.properties
   JDBC is c:\mysql-connector-java-3.1.14\mysql-connector-java-3.1.14-bin.jar
   MV_HOME is ..
   ENABLE_MGMT is false
   Using properties file multiverse.properties
   Using world file "..\config\sampleworld\sampleworld.mvw"
   Saving log files to ..\logs\sampleworld
   Java Flags are: -cp "..\dist\lib\multiverse.jar;..\dist\lib\mars.jar;..\other\rh
   ino1_5R5\js.jar;..\other\java-getopt-1.0.11.jar;..\other\jython_2_1.jar;c:\mysql
   -connector-java-3.1.14\mysql-connector-java-3.1.14-bin.jar" -Dmultive
   rse.propertyfile=multiverse.properties
   Starting domain server:         SUCCESS
   Starting animation server:      SUCCESS
   Starting combat server:         SUCCESS
   Starting object manager:        SUCCESS
   Starting login manager:         SUCCESS
   Starting world manager 1:       SUCCESS
   Starting proxy server:          SUCCESS
   Starting world reader:          SUCCESS
   Starting mob server:            SUCCESS
   Wait for finished initializing msg...
   

Confirm servers are running

After the messages from the startup script, the first time you run the servers, you may see some further messages from the Java Runtime Engine that look like this:

*sys-package-mgr*: processing new jar...

Then, you will see:

Wait for finished initializing msg...

And after a few seconds:

DONE INITIALIZING, you can log in now

This indicates the servers have initialized. Finally, confirm that the servers are all runnning properly.

Windows (no Cygwin)

Enter this command:

status-multiverse.bat

If the servers are all running properly, you will see this output:

Animation server: running
Combat server: running
Login server: running
Mob server: running
Domain server: running
Object server: running
Proxy server: running
World manager: running
World reader: running

Linux or Windows (Cygwin)

Enter this command:

./multiverse.sh -v status

If the servers are all running properly, you will see this output:

domain server: RUNNING login server: RUNNING animation server: RUNNING combat server: RUNNING object manager: RUNNING world manager 1: RUNNING proxy server: RUNNING world reader: RUNNING mob server: RUNNINGG

If you see this, you can proceed to log in with the Multiverse Client. Otherwise, see the Troubleshooting section.

Troubleshooting

If you encounter problems starting the servers, see Server Troubleshooting for some suggestions.

Connect to servers with Multiverse Client

To set up the Multiverse Client to connect to the sampleworld, you must do two things:

1. Download and designate an asset repository containing the 3D assets. If you followed the previous section Download and designate asset repository, then you have already done this.
2. Enable your Multiverse Client to find your servers. There are two ways for the Multiverse Client to find and connect to your servers:
   • Local servers: if you are running the Client and the servers on the same machine, connect use the special "localhost" world. See Connect to local servers below for details.
   • Remote servers: if you are running the servers on one machine and the Client on another, register your world with Multiverse, to enable your Client to find and connect to your servers. See Connect to remote servers below for details.

Confirm asset repository

Make sure you have downloaded and installed an asset repository, and designated as your default asset repository, as described previously in the section Download and designate asset repository.

To confirm that you have designated a local asset repository, run any of the Multiverse tools; if they prompt you to "Download and Designate" an asset repository, then you have not yet done so.

You must complete this step to be able to continue and run the sampleworld.

Connect to local servers

If you are running the Client and the servers on the same machine, connect to the machine using the special "localhost" world registration set up by Multiverse. When the client tries to connect to this world, it will actually connect to the world running on the local system.

Open a Windows Command Prompt window, and enter these commands:

cd c:\Program Files\Multiverse Client\bin
MultiverseClient.exe --development --world localhost

The --development command line option combines the effects of two other individual command line options:
   --use_default_repository, which makes the client use the asset repository you designated for the tools; it will only work if the server and tools are running on the same system
   --frames_between_sleeps 2 option, which makes the client yield CPU cycles to the server after rendering every two frames; this ensures the server processes get enough CPU cycles to run properly when client and server are running on the same system.

If you need to work offline (that is, without an internet connection), then you must follow a different procedure; see World Settings File Reference.

When the client starts, it will first update itself. Then, it will immediately try to connect to the specified servers (it doesn't need to download media assets because it is using the local default asset repository).

Connect to remote servers

If you are running the client and servers on different machines, you must register your world with the Multiverse master server; this enables any remote client to connect to your world. Follow the steps in Registering a World with the Multiverse Network. Make a note of the "World ID" that you enter when you register your world.

Note: Initially, make your world "private" because you don't need anyone else to connect to it. You'll use a special command-line option to connect to select your world until it becomes public.

Open a Windows Command Prompt window, and enter these commands:

cd c:\Program Files\Multiverse Client\bin

If there is a local asset repository, and you have designated it as the default asset repository, then enter the command:

MultiverseClient.exe --development --world world_ID

where world_ID is the unique world ID you entered when you registered your world.

If you do not have a local asset repository, but have configured a network asset repository, and have specified it when you registered your world, then enter the command:

MultiverseClient.exe --world world_ID

where world_ID is the unique world ID you entered when you registered your world.

First, the Client will update itself. Then it will download media assets from the specified network asset repository. While it downloads, it will display the patcher page specified when you registered the world.

In Sampleworld

When the Client connects to the servers, you will see a splash screen and the Client will enter the sample world.

Move around the sample world and check things out. For information on using the client and default key bindings, see Using the Multiverse Client.

When you are done, type "/quit".

Troubleshooting

If you cannot connect to the server see Server Troubleshooting and Client Troubleshooting.

Stop the servers

On Windows, stop the Multiverse servers by entering this command in the Command Prompt window:

stop-multiverse.bat

This will terminate all the running Java processes on your machine.

On Linux (or with Cygwin on Windows), stop the Multiverse Servers by entering this command in the Cygwin window where you started them:

./multiverse.sh stop

Next steps

If you are interested in exploring the Multiverse tools, and creating your own world to run on the servers, then go to the next article in the Multiverse Platform Tutorial: click "Next" below.

If you'd like to browse all the rest of the Multiverse documentation, check out Developer Quick Links.

Running Fantasy Demo World

The server distribution includes another world, the Multiverse Demo Fantasy World (mv_fantasy). It has its own assset repository, available in a separate download. Fantasy World has more complex examples of gameplay such as quests, abilities, and teleporters. Multiverse also runs Fantasy World "live" online on a public server.

To run Fantasy World:

1. Download the Fantasy World asset repository and extract the zip file.
2. Edit the server property file and change multiverse.worldname=sampleworld to multiverse.worldname=mv_fantasy.
3. In the tools, add the mv_fantasy asset repository root directory to your list of default asset repositories. You can do this in any of the tools, but for example in Model Viewer:
   1. Choose File | Designate Asset Repository.
   2. Click Browse and Add Directory.
   3. Browse to the directory where you extracted the Fantasy World asset repository, then select the root mv_fantasy directory, then click OK.
   4. Click OK in the Designate Asset Repositories dialog box.
   5. Exit Model Viewer.
4. Run the Client with the --development and --world localhost command-line options.

Create your own world

Subsequent tutorials cover using World Editor to create your own world, but if you're impatient, you can create a "clone" of sampleworld with which to start working. Follow these steps:

1. Create a new directory in the mv-home/config directory called "myworld", or whatever name you choose.
2. Create a new world with World Editor, and save the world file to the directory you just created. Note: you can use another directory, but generally it's easiest to keep all a world's server files (incluiding the world file) in the config subdirectory.
3. Edit your server properties file, mv-home/bin/multiverse.properties and change the line

   multiverse.worldname=sampleworld
   

   to

   multiverse.worldname=myworld
   

   Where myworld is the base name of your world file. That is, if your world file is foo.mvw, then the world name is "foo".
4. Copy ALL the .py files from mv-home/config/sampleworld to mv-home/config/myworld.
5. Optional: in World Editor, add a spawn marker for your player spawn location, as described in How To Specify the Player Spawn Location.
6. Start the servers.
7. Start the client with --development and either --world localhost (to connect to the local server) or --world worldID (for a remote server).

You will enter your world.

Creating your own terrain

If you want to create your own terrain, follow these instructions:

1. Launch the Multiverse Terrain Editor.
2. Fiddle with the options until you get a piece of terrain you like. Save it with a name you like.
3. Launch the Multiverse World Editor.
4. Select File > New World. Enter a name.
5. In the upper-right section (according to the World Editor documentation, this is called the "Tree View"), expand the tree until you see a subtree called "Terrain."
   • If you don't have a "Tree View" in your editor, then you may have the wrong (old) version of the tools. See the above intro about that.
6. Right-click on "Terrain" and select "Load Terrain." Select the terrain file you just created in the Multiverse Terrain Editor.