Tutorial: Writing scripts

Scripts in Openplanet are written in Angelscript. A quick overview of the Angelscript syntax can be be found here.

There are 2 locations where Openplanet will search for scripts:

  • [ManiaPlanet]/Openplanet/Scripts/
  • C:/Users/[Username]/Openplanet4/Scripts/

The first folder is installed by Openplanet and contains all the scripts that Openplanet ships with. You should not modify these scripts here or put other scripts here, because any Openplanet update will delete all the contents of this folder. Instead, you have to put your own scripts or script modifications in your user folder.

Tip: You can open your user folder via the Openplanet overlay as well:

Creating your plugin file

Go to your user scripts folder, and create a new file called Plugin_MyFirstScript.as. Note that only files prefixed with Plugin_ will be considered for loading by Openplanet. This way, you can have separate script files that you can #include in your plugins as "libraries".

Starting the plugin

A plugin can have some metadata associated with it:

  • Name
  • Author
  • Category
  • Settings

These are set via precompiler options and field attributes. Let's start by setting the name and author of your first plugin. Place this at the top of your script:

#name "My first script"
#author "Miss"

Another thing we can add is a category, which will categorize your plugin in several parts of the overlay. You might want to consider using existing categories if your plugin fits within those. If you don't provide a category, it will be uncategorized and labeled as such.

#category "Cool"

You can specify this metadata for your plugin:

  • #name - the plugin's name
  • #author - the plugin's author's name
  • #category - the category the plugin shall be listed in
  • #perms - required permissions for the plugin. This is relevant for plugins signed for use in Trackmania (2020) for Starter (no perms line), Standard (#perms "paid") or Club (#perms "full") access. Unsigned plugins are only avaliable for Club access regardless of #perms metadata.
  • #min_game_version - minimum game version the plugin may be used with. The game version must be given in a format of "YYYY-MM-DD" or "YYYY-MM-DD HH-mm". Time must be given in 24-hour format.
  • #max_game_version - maximum game version the plugin may be used with.

We also need an entry point for the plugin, so put this just below:

void Main()
{
}

We'll leave the entry point empty for now. Next, in the Openplanet overlay, select Scripts -> Reload Scripts.

If you open the settings menu now (Openplanet -> Settings), you will see your new plugin under the "Plugins" tab.

If it does not show up, take a look at the log (Openplanet -> Log), which should tell you more about any errors.

Continue to the next page: Entry point execution

Edited 122 days ago by