Upgrading to Version 1.5

From Multiverse

Procedure

To upgrade a version 1.1 world to version 1.5, follow these steps:

1. As a precaution, back up your world. If you encounter problems, this will ensure you can always refer back to your original code.
2. Install the version 1.5 platform.
3. Recreate the Multiverse database. NOTE: You must perform this step if you ran the version 1.1 servers, even if you did not write any code.
4. Run Sampleworld
5. Convert your server scripts and Java code, if you have written or modified any.

Backup your world

As a precaution, make backup copy of all your server scripts, your world file, and your asset repository. On the server, the backup should include:

• The property file, by default multiverse.properties.
• Your world (.mvw) file, and all associated collection (.mwc) files.
• All files in mv-home/config/yourworld.
• All files in mv-home/config/common that you modified.
• Any Java code you have written or modified.

Keep a backup of your entire asset repository, including any files you modified in the /Scripts directory and /Interface/FrameXML directory.

Install new platform

Download and install the version 1.5 server, tools, and Sampleworld asset repository

Open one of the tools (say, Asset Packager), and set the new Sampleworld asset repository to be the default tools asset repository.

Using the server Java VM

The Multiverse servers require the "server Java Virtual machine", only available with the Java Development Kit (JDK), not the Java Runtime Engine (JRE).

If you try to run the Multiverse servers with the JRE, you will get startup errors like the following:

...
Starting message domain server
Error: no `server' JVM at `c:\ProgramFiles\Java\jre1.5.0_08\bin\server\jvm.dll'.
Error: no `server' JVM at `c:\Program Files\Java\jre1.5.0_08\bin\server\jvm.dll'.
...

For information on the differences between client and server VMs, see Sun's document Java Virtual Machines.

To determine whether you can run the server JVM, enter this command:

java -server -version

This command should return something like this:

java version "1.5.0_08"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_08-b03)
Java HotSpot(TM) Server VM (build 1.5.0_08-b03, mixed mode)

The exact version it shows may be different, depending on the version of the JRE and JDK you have installed. If you see something like the above, then you have the server Java VM, and you are OK.

Otherwise, it will return the error:

Error: no `server' JVM at `C:\Program Files\Java\jre1.5.0_09\bin\server\jvm.dll'.

In this case, you need to make some configuration changes. Follow these steps:

1. The error message tells you where Java is looking for the VM, in this example in C:\Program Files\Java\jre1.5.0_09\bin. You'll notice that this directory has a \client sub-directory, but not a \server sub-directory.
2. Find the directory where your JDK is installed, usually somewhere like C:\Program Files\Java\jdk1.5.0_04. Under that directory, you will see a sub-directory \jre\bin\server that contains the server JVM.
3. Copy the server JVM directory from the JDK directory to the JRE directory. So, for example, copy C:\Program Files\Java\jdk1.5.0_04\jre\bin\server to C:\Program Files\Java\jre\bin. Now the JRE bin directoy will have a server sub-directory as well as a client sub-directory.

It shouldn't matter if the JRE and the JDK are different patch releases (for example, _04 vs _11). But they should have the same point number (for example, 1.5.0).

Confirm that you can use the sever JVM by typing "java -server -version" again. You should see the version of the JDK instead of the error message.

Recreate the Multiverse database

In version 1.5, the database schema has changed, so you must regenerate the database. Even if you have not written any code, if you have previously installed the Multiverse servers, you must perform this step.

On Linux (or in a Windows command shell window), if you have MYSQL_HOME/bin in your PATH environment variable, start the MySQL Command Line Client as follows:

cd mv_home/bin
./mysql --user=username --password=password

Where username is the root account username (by default, "root") and password is the corresponding password, "test" by default.

On Windows start the MySQL Command Line Client by choosing Programs | MySQL | MySQL Server X.X | MySQL Command Line Client.

You will be prompted for your password. By default, user name is "root" and password is "test."

1. Delete the existing Multiverse database. In the MySQL Client, enter the command:

    mysql> drop database multiverse;
   

2. Create the database with the new schema. In the MySQL Client, enter the command:

    mysql> source MV_HOME/bin/install.sql
   

   Where MV_HOME is where you installed the 1.1 server. For example, if MV_HOME is C:/multiverse, enter

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

The MySQL Client will display a number of lines such as the following:

Query OK, 1 row affected (0.03 sec)

Database changed 
Query OK, 1 row affected (0.03 sec)
...

Confirming 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     |
| plugin_status        |
+----------------------+
5 rows in set (0.00 sec)

If you don't see a "namespaces" table, then the database was not created properly.

If the database looks OK, exit MySQL command line client with this command:

mysql> exit;

Database differences

The database schema has changed in the following ways:

• The instance column has been added to the objstore table. The instance column contains the object's current instance oid. This column is only set on the world manager namespace.

Run Sampleworld

Once you have converted your database, run Sampleworld to confirm your server installation:

1. Start the 1.5 servers, running Sampleworld.
2. If you are running the servers on the same machine as the Client, use the default world settings file: rename world_settings_sample.xml to world_settings.xml. If you are running the servers on a remote machine, use the --world option command-line option, specifying Sampleworld on your server.
3. Run the Client using the --development command-line option, being sure that you have designated the new Sampleworld asset repository as your default repository (with the Multiverse tools).
4. Log in and make sure you can move around Sampleworld. You will see a short demo of "in world" video featuring Multiverse Executive Producer Corey Bridges and CTO Rafhael Cedeno, as well as an example of displaying a web page (the Multiverse website home page) on an in-world object.
5. Exit the Client. You are ready to start upgrading your world.

Convert multiverse.properties

The definition of plugin dependencies has changed in 1.5 (the "plugin_dep" entries in multiverse.properties). If you modified multiverse.properties, or use your own properties file, then you will need to make changes. The easiest approach is to merge your changes into the new 1.5 multiverse.properties file.

In addition, the voice server has added several new properties.

Convert server code

See the following section.

Convert server code

NOTE: There have been several significant changes in the server API in this release, in particular in the spawn generators. Read this section to determine which of your scripts and Java code you need to convert to version 1.5.

mobserver.py changes

The definition and creation of spawn generators has changed in 1.5 due to the introduction of instancing. Previously, spawn generators were created in mobserver.py which was run when the mobserver started. In version 1.5, instances are not created or loaded until after the mob server has started. Spawn generators are now created when instances are created or loaded. Instances have associated initialization and load scripts which can perform this function. However, these scripts are run within the InstancePlugin process, not the mob server process. A mob server API has been added to allow remote creation of spawn generators. However, you must still define ObjectFactory classes in the mob server process. The end result is that existing mobserver.py scripts must be split, moving the spawn generator creation into the instance script.

Functionality that stays in mobserver.py

• ObjectFactory class definitions
  • New: ObjectFactory instances must be registered using ObjectFactory.register()
  • New: ObjectFactory sub-classes must override makeObject(SpawnData spawnData,long instanceOid,Point loc)
    The same parameters must be passed to ObjectFactory.makeObject()
• SpawnGenerator sub-class definitions
  • New: SpawnGenerator classes must be registered using MobManagerPlugin.registerSpawnGeneratorClass()
• Quest object creation -- quest objects are generally global objects referenced by ObjectFactory code, so don't need to be registered.

Functionality that moves to instance script:

• Marker lookup (for spawn generator location)
• SpawnData definition
  • Add object factory name
  • Add instance identifier
• Spawn generator creation, using MobManagerClient.createSpawnGenerator(SpawnData)

ObjectFactory upgrade steps

1. Add parameters to makeObject() override:

    class Npc1Factory (ObjectFactory):
        def makeObject(self, loc):
   

    class Npc1Factory (ObjectFactory):
        def makeObject(self, spawnData, instanceOid, loc):
   

   The spawnData is the SpawnData used to create the spawn generator. The instanceOid is the instance identifier. The loc is the object spawn point, as before.

2. Add parameters to super-class makeObject() invocations. If your object factories use ObjectFactory.makeObject() to create objects, you need to add two parameters:

           // inside makeObject() method 
           obj = ObjectFactory.makeObject(self, loc)
   

           // inside makeObject() method
           obj = ObjectFactory.makeObject(self, spawnData, instanceOid, loc)
   

3. Move WorldEditorReader.getWaypoint() from global to class scope and change to InstanceClient.getMarkerPoint()

    wolfLoc = WorldEditorReader.getWaypoint("wolfmarker")
   

            // inside makeObject() method
            wolfLoc = InstanceClient.getMarkerPoint(instanceOid, "wolfmarker")
   

4. Register ObjectFactory instances using ObjectFactory.register()

    class WolfFactory (ObjectFactory):
       def makeObject(self, spawnData, instanceOid, loc):
           obj = ObjectFactory.makeObject(self, spawnData, instanceOid, loc)
    
           wolfLoc = InstanceClient.getMarkerPoint(instanceOid, "wolfmarker")
           # add behavior
           behav = RadiusRoamBehavior()
           behav.setCenterLoc(wolfLoc)
           behav.setRadius(20000)
           obj.addBehavior(BaseBehavior())
           obj.addBehavior(behav)
           obj.addBehavior(CombatBehavior())
           return obj
    
    ObjectFactory.register("WolfFactory", WolfFactory("Wolf"))
   

5. Remove all code that instantiates ObjectFactory or its sub-classes; this code will move to the instance script
6. Remove all code that instantiates SpawnGenerator or its sub-classes; this code will move to the instance script

Creating spawn generators in instance script

Instances have two scripts; an initialization script run once when the instance is created, and a load script run each time a persistent instance is loaded. Typically, a persistent instance has both an init and load script while a non-persistent instance only has an init script. Spawn generators are not persistent, so must be created in both the init and load scripts.

Note that it's now possible to control spawned object orientation using the marker orientation. This it helpful when placing immobile objects.

The following steps assume a non-persistent instance with an instance init script named "instance_init.py". When defining your instance template, set the instance init script to "instance_init.py", for example:

template.put(Namespace.INSTANCE, InstanceClient.TEMPL_INIT_SCRIPT_FILE_NAME, "$WORLD_DIR/instance_init.py")

1. Add the following to the top of instance_init.py:

   from java.lang import Long
   from multiverse.server.plugins import *
   from multiverse.server.objects import *
   
   instance = Instance.current()
   instanceOid = Instance.currentOid()
   

   The instance and instanceOid are the current instance object and instance oid.

2. Use instance.getMarker() to get markers (formerly waypoints) for spawn generator locations. If you need to modify the marker, then you should clone it.

   wolfMarker = instance.getMarker("wolfmarker").clone()
   wolfMarker.getPoint().setY(0)
   

3. Create SpawnData and initialize factory and instance oid. The factory name is the one registered with ObjectFactory.register().

   spawnData = SpawnData()
   spawnData.setFactoryName("WolfFactory")
   spawnData.setInstanceOid(Long(instanceOid))
   

4. Initialize other SpawnData settings. Use the marker to get the spawn generator center point.

   spawnData.setLoc(wolfMarker.getPoint())
   spawnData.setOrientation(wolfMarker.getOrientation())
   spawnData.setNumSpawns(3)
   spawnData.setSpawnRadius(20000)
   spawnData.setRespawnTime(60000)
   

5. Create the spawn generator. This makes a remote call to the mob server.

   MobManagerClient.createSpawnGenerator(spawnData)
   

WorldEditorReader.getWaypoint() replaced

The API WorldEditorReader.getWaypoint() has been replaced by InstanceClient.getMarkerPoint(). Markers are contained in an instance, so an instance oid is required to access a marker.

point = InstanceClient.getMarkerPoint(instanceOid,"marker name")

InstanceClient APIs exist to get complete marker objects, including marker orientation and marker properties.

marker = InstanceClient.getMarker(instanceOid,"marker name")
marker = InstanceClient.getMarker(instanceOid,"marker name",InstanceClient.MARKER_ALL)

The former gets the marker location and orientation. The latter gets the marker location, orientation, and properties.

ProxyPlugin API changes

The following method name changes have been made:

• registerExtensionMessage() changed to registerExtensionSubtype()
• unregisterExtensionMessage() changed to unregisterExtensionSubtype()
• findExtensionType() changed to getExtensionMessageType()

Object persistence flag

TODO

• must enable object persistence when object created
• saving an object no longer enables persistence for the object
• Multiverse Object Architecture#Persistence

Character factory changes

TODO - this is already covered in World Instancing#Character_Creation

• set persistence flag
• initialize instance restore stack

Plugin name changes

TODO

• Configuring Agents and Plug-ins

Plugin types

TODO

• plugins must have a plugin type
• plugin dependencies expressed in terms of plugin types instead of plugin names

Update assets

Modify diffuse bump shader program

In previous releases, the sample assets included a shader that had an error in it, but the shader compiler would ignore the error. The 1.5 Client uses version 2.0 of the NVIDIA Cg compiler, and it now correctly generates an error when compiling the shader.

The shader is in the file \GpuPrograms\DiffuseBump.cg in your asset repository. YOU MUST replace the old version of this file with the new version in the 1.5 sample assets to be able to run your world with the 1.5 Client.

You may also download this file individually and replace the old version in your asset repository.

Remove obsolete script statements

Make sure you have removed all the obsolete client API calls described in 1.1 Client API Updates. In addition, remove any instances of the following:

from Multiverse.Interface import *
from Multiverse.Network import *
from Multiverse.Config import *
from System.Diagnostics import Trace
from Axiom.SceneManagers.Multiverse import WorldManager
from Axiom.Core import ColorEx
from Axiom.Input import KeyCodes
from Axiom.Input import MouseButtons
from Axiom.Input import KeyboardEventHandler

These statements will cause various Client errors. Check Inteface\FrameXML\Library.py for such lines. The Library.py file from version 1.0 contains these statements. Generally, you should use Library.py provided with the 1.5 (or 1.1) assets, not the 1.0 version.