Bringing over legacy scripts

A world from the original Odyssey brings its scripts with it. When you convert your server, every script is translated from the language the old server used, MBSC, into C#, which is what this server runs. Most need nothing more from you.

This guide shows what the translation does, how to find the scripts that need a hand, and how to fix them.

What conversion does to a script#

Here is a script as the old server had it, named JOINGAME:

Function Main(Player As Long) As Long
  Dim Level As Long
  Level = GetPlayerLevel(Player)
  If Level < 5 Then
    PlayerMessage(Player, "Welcome! Stay near town until you are stronger.", 14)
  Else
    PlayerMessage(Player, StrCat("Welcome back, ", GetPlayerName(Player)), 10)
  End If
  Main = Continue
End Function

and as it arrives in your converted world:

bool main(int player)
{
  int Level = 0;
  Level = GetPlayerLevel(player);
  if (Level < 5)
  {
    PlayerMessage(player, "Welcome! Stay near town until you are stronger.", Yellow);
  }
  else
  {
    PlayerMessage(player, StrCat("Welcome back, ", GetPlayerName(player)), BrightGreen);
  }

  _mainReturnValue = true;
  return _mainReturnValue;
}

It does the same thing, line for line. What changed:

_mainReturnValue is where the translation keeps what Main was set to. You can leave it, or tidy the script to return true;.

The functions keep their names. GetPlayerLevel, PlayerMessage, SetPlayerFlag and the rest work as they did, and the script reference lists them all.

The original is kept#

Nothing is thrown away. In Odyssey Server Admin, open Scripting and choose a converted script: it has two tabs.

• Script is the C# the server runs.
• Legacy source (MBSC) is the script as it was on the old server.

The list marks these scripts Legacy, and the Converted from legacy filter shows only them.

Convert to C#, on the legacy tab, translates the MBSC again and puts the result on the Script tab. Nothing is saved until you press Save, so you can look first.

Finding the scripts that need you#

After converting, start your server, open Scripting, and choose the Needs attention filter. It lists the scripts the server cannot run. To be sure it has looked at every one, press Check all first: it compiles every script and reports how many failed.

A script that needs you is in one of two states.

Not converted#

A handful of scripts cannot be read as MBSC at all, nearly always because of a slip the old server let through, such as a misspelt End Function. The list marks these Not converted, and the script opens with a banner saying what the translation stumbled on.

1. Open the Legacy source (MBSC) tab.
2. Correct the line the banner names.
3. Press Convert to C#. The app answers Converted. Review it, then Save.
4. Press Save.

Quarantined#

Other scripts translate, but the result does not compile. The list marks these Quarantined, and the Problems panel lists each error with its line.

The usual cause is a call to something this server does not have, which reads like this:

The name 'SetPlayerPosition' does not exist in the current context

Look the function up in the script reference. Often it has a near neighbour, here PlayerWarp. Fix the C# on the Script tab and press Save. A script that compiles leaves quarantine by itself.

A quarantined script is skipped, and the server carries on as if it were not there. Your world runs while you work through the list.

Differences worth knowing#

Yes and no are the other way round. In MBSC, Continue was 0 and Stop was 1. In C#, carrying on is true and stopping is false. The translation takes care of this in every converted script. It matters when you write a new one from memory of the old.

Values are matched by name. The old server handed Main its values by position, and a script could call them anything. This server matches them by the names on the events page, so a script takes only the ones it wants. The translation renames them for you.

A script that asks for more than its event gives still runs. Some old scripts declared a value their event never supplied and used it as a spare variable. They run here too, with that value starting at 0 or empty, and the server's log notes it once.

Pause does nothing, as it did nothing on the old server. To make something happen later, use ScriptTimer.

Access levels are gone. Who may do what is decided by roles and rights, under Player administration. GetPlayerAccess still answers a number from 0 to 10 worked out from a player's rights, so scripts that test it keep working. SetPlayerAccess does nothing: give the player a role.

Scripts cannot touch the machine. A script here cannot read or write files or reach the network. ReadINIStr, ReadINIInt, WriteINIStr and PrintToFile still work: the server keeps what they store.

A runaway script is stopped. A script caught in a loop that never ends is stopped and quarantined, and everything else carries on.

Warnings#

A converted script that compiles may still show Warnings in the Problems panel. They do not stop it running.

Most are about functions the old language needed and C# does not: StrCat to join text, StrCmp to compare it, RunScript0 to RunScript4. They work today, and the warning says they will be taken away in a later version. The last section of the script reference shows what to write in their place. There is no hurry, and it is a good way to learn the new language: change one, save, see that it still works.

Worlds from Odyssey Classic#

Odyssey Classic added magic, skills and prefixes and suffixes on items, and functions for scripts to use them. This server does not have those systems. Their functions are accepted, so a script that calls them compiles and runs, but each does nothing, and the server's log says so the first time one is called. Parts of a script that depend on them will need rethinking.

Before a server update#

A new version of the server can change what scripts may call. When you install an update from Odyssey Server Admin, its Script check step compiles every script in your world against the new version first and lists any that would stop working, so you can fix them before your players meet them. Backups and updates describes the steps.