.NET Core plugin for VCMP

Started by EK.IceFlake, Aug 27, 2018, 02:06 PM

Previous topic - Next topic

EK.IceFlake

Intro
I've been wanting .NET support in VCMP since over two years now. Now that I have the skills to actually attempt something like this myself... well, I decided why not take a go at it. So put simply this is a collection composed of
  • a VCMP plugin that serves as a CoreCLR host;
  • a .NET interoperability library that basically serves as a VCMP .NET plugin SDK; and
  • hopefully, a wrapper that abstracts the SDK away and provides an experience that feels similar to using other .NET libraries, with OOP paradigms and stock .NET interfaces.

Repository
The main repository of this project can be found on GitLab. You can use this repository for
  • getting its source code;
  • getting pre-built versions of this project;
  • documentation about this project; and
  • reporting bugs and getting support about this project.

dotnet-vcmp repository

Additional support
You can get quick support about this plugin at Developers.cpp. However, if you want more complex or advanced support, you should create an issue on GitLab. This is so that I help not only you but any potential future users of this project as well.

Developers.cpp

Builds
Since I use Linux as my OS, it's not particularly easy for me to support Windows as well. All pre-built binaries you see here are tested on Linux 64 bit. The C# interoperability DLL will very likely work on Windows 64 bit as well. Do not try to use them on a 32 bit architecture - they will not work! I've made the source code platform-agnostic, so you can compile a 32 bit version yourself if you need to.

Note that you should add Fleka.DotnetVcmp.Interop as a Nuget dependency instead of using the DLL directly.


Compiling
The VCMP plugin uses the Meson build system. You need to have Meson installed in order to compile it. If you're on Windows, I recommend that you use Meson to generate a Visual Studio solution and compile it using Visual Studio.

Use dotnet build or dotnet publish to build a managed assembly.

Getting Meson
Meson compilation guide

Setting up a hello world application
  • Installing .NET Core
    .NET Core supports Windows and lots of Linux distributions. Since I can't comprehensively cover all of them here, you can find instructions at Microsoft's official website.
  • Creating a project
    Enter the directory where you want to create your project and execute one of the following commands depending on the language you want to use:
    • C#: dotnet new classlib --language C#
    • F#: dotnet new classlib --language F#
    • VB.Net: dotnet new classlib --language VB
  • Adding the interoperability project as a dependency
    If you open your .csproj file, you should find a root Project tag. You shouldn't have an ItemGroup tag inside it by default, so you should add it manually. If that tag already exists, you don't need to add it. Create a new tag inside ItemGroup with the following content:
    <PackageReference Include="Fleka.DotnetVcmp.Interop" Version="1.1.0" />
  • Creating your class
    You should find a .cs file in your project directory. Replace its contents with the specified test app class.
  • Compiling
    Execute dotnet publish in your project directory.
  • Setting up the server
    After placing the plugin in plugins/ and adding it to server.cfg, create a file called dotnet.json with the specified content. You might need to change clr.runtime-directory to point to your runtime's directory. If you're on Linux, you can execute locate libcoreclr.so to locate it. You can now create a directory called dotnet-assemblies/.
  • Installing your script
    To install your script, copy all DLL files from build/debug/netstandard2.0/publish/ to dotnet-assemblies/. Note that if you update your script, you'll have to execute dotnet publish and copy the generated DLLs again.

.NET core installation instructions
Hello world test app class
dotnet.json example configuration

Windows
If you have an adequate Windows software development installation (with Visual Studio, Meson and .NET Core) and you don't need lots of help with this, you can contact me to volunteer to test and compile this plugin on Windows.

Side note
I don't recommend using this right now for developing scripts. It just exposes VCMP's raw API with no error checking at all, and you can easily run into segmentation faults, crashes or silent failures and you won't even be able to figure out why. You should really only be using this with a wrapper. I'll hopefully release an official wrapper soon, and you can also create unofficial wrappers if you like.

NicusorN5

Is there any documentation  on the functions, or I have to look into the source code?

EK.IceFlake

Quote from: Athanatos on Aug 29, 2018, 09:02 AMIs there any documentation  on the functions, or I have to look into the source code?
Right now, the project contains no documentation since it just exposes VCMP's SDK to .NET without any modifications. So for the time being, all functions behave exactly as they do with the plugin SDK. The plugin SDK contains documentation on which errors can occur from a function, but that's all. So for the time being, you'll have to look into the source code; either in C# (this project) or C++ (VCMP's SDK). You should also take a look at how marshaling is handled in .NET.

Bear in mind that this is just for the interoperability layer. The wrapper (which is currently in development) is extensively documented and exposes its own set of functions which are designed to make scripting easier and safer.

Plugin functions (implemented in C#)
Plugin callbacks (implemented in C#)
Plugin function signatures (implemented in C#)
Plugin callback signatures (implemented in C#)
VCMP SDK (implemented in C++)
.NET marshaling

Sir. Cucuruchito

Quote from: Athanatos on Aug 29, 2018, 09:02 AMIs there any documentation  on the functions, or I have to look into the source code?

Like everything related to Vice City Multiplayer, the documentation is conspicuous by its absence.
Only looks Java plugin documentation or Squirrel implementation.
Commando Miami 80's
IP: 206.189.97.12:8192