Getting Started with Scripting

From GT-MP
Jump to: navigation, search

Getting Started with Scripting

Introduction

If you are going to develop a lot in C#, it is recommended that you set up a solution with projects. This gives you a lot of benefits, as the most important one: autocompletion.

On this page you will learn you could set up your IDE (Visual Studio) in order to start scripting your own GT-MP Server.

Visual Studio

On of the best IDE for developing in C# is Microsoft's Visual Studio, which you can download here.

Attention: only Visual Studio Community is free of charge - for all the other versions there's a trial version available to download.

After the trial version you have to activate Visual Studio with an purchased key, but the Community Edition comes with a lot of common features.

Create a new solution

Let's start by creating a new solution. The theory behind this method of setting up Visual Studio is that the following "resources" folder is essentially our Visual Studio solution folder.

Start creating a blank solution with File -> New -> Project (or CTRL + Shift + N) and find "Blank Solution" in the project types. In Visual Studio 2015 and above, this is most likely under Templates -> Other Project Types -> Visual Studio Solutions.

Set the name of the solution to just "resources" and the location to where you have your GT-MP Server installed.

Getting Started with Scripting NewBlankSolution.png

Once you click OK, a new "resources.sln" is created in your resources folder and the empty solution will be opened in Visual Studio.


Creating a new project/resource

When you decide to create a new resource/project, all you have to do in Visual Studio is right click on the solution in the solution explorer, then Add -> New Project. You will have to find the "Class Library" project type and enter a name. The project name you enter in this dialog will be your resource name, so if you wanted to make a cool gamemode called "Destruction Derby", you will probably want to enter "destructionderby", "destruction-derby" or "dd" here.

Please note, some versions of Visual Studio will have 2 options available; Class Library (.NET Standard) and Class Library (.NET Framework). You need the latter (.NET Framework)

Getting Started with Scripting Create class library.png

When you click OK, your project will be created and the folder for your resource has also been created.

Manage NuGet Packages

In order to get autocompletion for the Scripting API, you will have to add (to each resource/project you create) references from the GT-MP API.

To do this, right click "References" in the solution explorer of your project and click "Manage NuGet Packages".

Getting Started with Scripting ManageNuGetPackages.png

After that, search for "grandtheftmultiplayer". It should give you two results from the Grand Theft Multiplayer Dev Team.

  • grandtheftmultiplayer.api (serverside API)
  • grandtheftmultiplayer.typescript (clientside API)

Getting Started with Scripting InstallGTMPNuGetPackages.png

Click on these items and click install on the right side and you're done!

Clientside automcompletion in Visual Studio

If you have successfully installed the packages mentioned , the "serverside" autocompletion is already available. In order to get autocompletion also for "clientside" scripting (JavaScript), you have to do just a few more configuration steps:

If you are running Visual Studio 2015 or 2013, you will have to install the TypeScript extension. For Visual Studio 2017, it should come pre-installed.
TypeScript 2.2 for Visual Studio 2015
TypeScript 2.3.1 for Visual Studio 2013

Make sure you have installed the second NuGet Package grandtheftmultiplayer.typescript Beside that, you will have to create a tsconfig.json file in your project root.

Getting Started with Scripting NewTypeScript.png

This is the configuration that TypeScript will use to generate the actual JavaScript files that the client will be executing. You can use this configuration: (you can tweak it of course, but make sure that compileOnSave is enabled.)

{
  "compilerOptions": {
    "alwaysStrict": true,
    "noImplicitAny": false,
    "noEmitOnError": true,
    "removeComments": false,
    "sourceMap": false,
    "target": "es6",
    "module": "commonjs"
  },
  "compileOnSave": true
}

You can then create a new TypeScript file (.ts) for your script. Note that the generated JavaScript file will have the same filename as the TypeScript filename, except with .js at the end instead of .ts. Once you have created your .ts file, add this line to the top of the file:

/// <reference path="types-gt-mp/index.d.ts" />

And you're done. Now begin typing things like API. and witness the autocompletion. When you save the .ts file, a .js file will be generated automatically if there were no TypeScript errors.

Getting Started with Scripting Clientside autocompletion.png

Setting up an existing resource

If you already have a resource that you would like to add to Visual Studio, the process is very similar as above, except when you try to create a project when a folder already exists. In that case you will get the following error message displayed:

Getting Started with Scripting ResourceAlreadyExists.png

As a workaround, please temporarily rename your existing folder (for example from "testing" to "testing-temp", then create the project by the process explained above and then manually move your files from the temp folder in the new folder. You can simply drag your files that you moved to the folder into your project.

And that's it. You are now ready to start developing resources with Visual Studio!

First Gamemode (Serverside)

If you have followed these configuration steps successfully, you can now focus on developing.

namespace DestructionDerbyGamemode
{
    public class DestructionDerbyGamemode
    {

    }
}


Start scripting

using GrandTheftMultiplayer.Server.API;

namespace MyGamemode
{
    public class MyGamemode : Script
    {
        public MyGamemode()
        {
            API.onResourceStart += MyGamemodeStart;
        }

        public void MyGamemodeStart()
        {
            API.consoleOutput("Starting \"MyGamemode\" Script!");
        }
    }
}

This simple server script will write a short message to the console, when the script will be started.

Execute your script within a GT-MP server

  • Copy your resource files (just your Sourcecode files - the auto generated folders of visual studio are not neccessary) to the "resource" folder of your GT-MP server.
  • Make sure, that you added an Meta.xml file for your gamemode to describe your gamemode and his associated files.
  • Add your gamemode folder to the resources, which should be loaded. (Settings.xml)