Log in Page Discussion History Go to the site toolbox

.Net Addons

From BluWiki


The .NET (speak: DotNet) Addon project is not considered stable.

The Ascent .NET Loader basically wraps Ascent's basic functionality into a .NET based API.

NOTE: Developers and users of Addons both need Microsoft's .NET Framework 2.0 (or higher) for Windows or Mono for most other platforms (untested) - See the Download Section

What is it?

The Ascent .NET-Addon loader is actually an Addon to Ascent itself. It is written in C++ and C++/CLI by Domi.
It provides a very clean and easily understandable .NET based API to Ascent which can be used by developers to develop Addons to Ascent in C# or any other of the .NET Framework's languages.
It is highly recommended to write .NET 2.0 compliant code though, so your Addon can also be used on platforms other than Windows, using Mono.

How to make it work?

NOTE: The following is written for users of VS 2008.

Get the .NET loader

  • Have Ascent compiled and fully setup with Debug-Configuration
  • Download AscentDotNetLoader
  • Copy the AscentDotNetLoader folder into your src/scripts/src folder (sorry, the src-folder is still a mess)
  • Start the AscentDotNetLoader.sln solution file (opens in VS 2008)
  • Compile and Run (in Debug-Mode)
  • Be patient: Since Precompiled Headers do not work with the /clr compiler-option, the build is rather slow!

If everything worked, you are ready to create your first .NET Addon.
Alternatively you can download the Sample .NET Addon, copy it to the src/scripts/src/DotNet - folder and skip the next two steps.

Create a new Addon

  • Create new Project (eg. MyFirstDotNetAddon): If you have a full version of VS 2008, you can now just create a new Project within the same solution. If not, you have to open VC# externally and create a new Project there.
  • Project-Settings: Create it in the src/scripts/src/DotNet folder (do not create directory for Solution) and then go to Project properties:
    • Application
      • Target Framework: .NET Framework 2.0 (so we can also use it on Mono)
    • Build
      • Check Define Debug constant (so we can debug)
      • Set Output Path to: ..\..\..\..\bin\Debug\script_bin\DotNet\
    • Debug
      • Start external Program: ../../../../bin/Debug/ascent.exe
      • Working Directory: ../../../../bin/Debug/
  • Add the DotNetLoader as a reference: Either choose it from the Projects-tab (if in same solution) or from disc (in the Bin/Debug/script_bin folder)

Write code!

Let's start by renaming the Class1.cs file to MyFirstDotNetAddon.cs (which will also ask you to rename the containing class).

Now where is the API?
Answer: In the Ascent.DotNet namespace.

And where do we start?
Answer: With the Addon-class which we have to derive in order to define an EntryPoint to our Addon (the point where our code starts getting executed).

Sample Code:

using System;
using System.Collections.Generic;
using System.Text;

using System.Reflection;

using Ascent.DotNet;

namespace MyDotNetAddon {
    public class MyFirstDotNetAddon : Addon {
        public override void Init() {
            // The entry point of our Addon!
            Console.WriteLine();
            Console.WriteLine("HELLO WORLD!");

            Console.WriteLine("All of the world's properties:");
            Utils.FilterProperties(typeof(World), delegate(PropertyInfo prop) {
                Console.WriteLine("\t" + prop.Name + ": " +
                    prop.GetGetMethod().Invoke(null, null).ToString());
            });

            ServerHooks.Instance.InitHooks();
            String chanName = "Trolls";
            ServerHooks.Instance.Chat += delegate(Player player, MsgType msgType,
                    Language lang, String message, String target) {
                if (msgType == MsgType.CHANNEL && chanName.Equals(target)) {
                    if (lang != Language.TROLL) {
                        // not implemented yet
                        //chan.Kick(player, "Only trolls are allowed.");
                    }

                    Console.WriteLine("{0} ({1}): {2}", player, target, message);
                }
            };

            ServerHooks.Instance.EnterWorld += delegate(Player player) {
                // is there already someone with the same name?
                Player other = Player.Get(player.Name);
                if (other != null) {
                    player.SendMsg(MsgColor.RED, "Your name is used by another player in {0} - Say hello to him!", other.MapManager.Name);
                    player.TeleportTo(other.MapManager.Id, other.MapManager.InstanceId, other.Pos);
                }
            };
            
            Console.WriteLine();
        }

        public override string Name {
            get {
                return "My sample Ascent .NET Plugin";
            }
        }

        public override void Destroy() {
            // not used atm
        }
    }
}

Create the Addons.txt file

This file contains all Addons that are to be loaded.
Add a new text-file called Addons.txt to the bin\Debug\script_bin\DotNet folder and copy the following into it:

# First Parameter: The name of the created dll-file (which by default carries the Project-name) WITHOUT .dll at the end
# <Space>
# Second Parameter: Fully qualified name of the Addon-class to be used (must include namespace)
MyDotNetAddon MyDotNetAddon.MyFirstDotNetAddon

Every Addon needs one line in this file.
If you are using external libraries, also mention them in that file and leave out the second parameter.

Debug it

Run the project and see how Ascent starts, loads the DotNetLoader-addon which then again loads your sample .NET addon.
See Screenshot

What is possible?

Functionality is limited: The core API is done but a lot of features still have to be added. Minor Core patches might still be required.
In addition to the sample code above, you can just double-click on the DotNetLoader in the list of References to open the Object Browser or simply inspect its code.
Most interesting would probably be the following classes:

  • ServerHooks (allows you to hook to all misc server-events)
  • ScriptMgr (allows you to define custom AIs and GameObject behavior)
  • World (has a (very limited) set of static methods and properties to get infos from/interact with the world)

What can go wrong?

Everything could go wrong. The addon is written in very clean code so bugs can easily be fixed, but it has in fact not been tested a lot yet.
Please be aware that their could be quite a few memory leaks.

Feedback!

In order to improve the .NET loader, YOUR feedback is needed:
Join the discussion on the boards.


Criticism

Slow Performance

C# code does not compile into native code but into Bytecode which will then be interpreted by a Virtual Machine which is a program to emulate another kind of environment. This extra layer of a program being interpreted by another program results into a minor performance loss.
In addition, the Ascent .NET Loader works as a managed Plugin to the native application Ascent. Because of this this we have to add an interface between them as another performance reducing layer. The worst is the fact that the 2 parts of the program (Native and .NET) do not share a common heap.
Feel free to make performance tests and find out how .NET Addons perform in comparison to native C++ Addons or Lua (of course we would also appreciate it if you could share these information with the community).

OS Independence

Although the .NET Framework was intended to be platform-independent by the creators, it did not quite come that far since it is now being developed by Microsoft, thus officially only runs on Windows. Users of other platforms can use Mono to run .NET application. Mono up to this point only supports .NET 2.0.

Quote by the author

I am aware of the fact that the .NET framework is not the number one choice of every developer, 
especially because of its poor support on non-windows platforms. I must say that I created this 
project mostly for myself. Now I see that it became quite a nice tool for every Ascent admin who is 
interested in .NET and has the means to run it on their own server.
No one is FORCED to use it.

Related Links

.NET Framework

Project downloads and links

Other

Site Toolbox:

Personal tools
GNU Free Documentation License 1.2
This page was last modified on 20 March 2008, at 17:19.
Disclaimers - About BluWiki