Log in Page Discussion History Go to the site toolbox

C Addons

From BluWiki


This is a tutorial for Ascent Addons written in C++. This tutorial is made for developers who use VS 2008 on Windows, but developers with other IDEs can also find out what the basic requiremens are to have custom C++ Libraries integrated into Ascent.
If you already know how to create addons, you might still be interested into Understanding the Ascent Code.

Note: This guide is for Windows. See the Linux guide if you're running a Linux server instead.

Requirements

Create a new Addon

You can find already existing addons in the src/scripts folder. If you use Visual Studio, just select the *.sln file that matches your version from this directory (eg scripts2008.sln for VS 2008). The source code is in the src-subfolder and I can only recommend to take a look at it for reference. It is also strongly recommended to add the ascent-world project to the scripts-solution so you can look into the Ascent source while writing your Addon and lookup symbols that you want to make use of.

Create a new C++ Project

  • Choose Win32 Console Application.
  • Give it a name.
  • Select Add to Solution and choose the location to be in Ascent's src/scripts/src folder.
  • Under Application Settings, select DLL and Empty Project.

The new project has now been created.

Edit the Project's Configuration Properties

Next I recommend to compile the empty project once (for some reason, the C/C++ - Menu in the Properties pages of the project doesn't show up for me before compiling the first time).

Then adjust the Project's Property-Settings: Make sure, you have the Configuration set to Debug in the Top Bar (we want to debug and test it before we go live) and of course also ensure that you built Ascent with Debug-configuration as well, so we can *debug* it more easily

  • General
    • Change the Ouput Directory to ..\..\..\..\bin\$(ConfigurationName)\script_bin (the script_bin directory within Ascent's output-directory, depending on Debug/Release version).
    • Change Character Set to Use Multi-Byte Character Set.
    • Make sure that there is No Common Language Runtime support (unless you want to make use of the .Net Framework, which is only recommended if you exactly know what that means for Ascent and the Servers that it runs on)
  • Debugging
    • Set the command to ..\..\..\..\bin\$(ConfigurationName)\ascent-world.exe (Ascent's executable)
    • Set the Working Directory to ..\..\..\..\bin\$(ConfigurationName) (Ascent's output-directory; the ConfigurationName - variable would be Debug or Release)
  • Linker
    • General
      • Set Additional Library Directories: ../../../../bin/$(ConfigurationName)/
    • Input
      • Set the Linker's Additional Dependencies: ascent-world.lib
  • C/C++
    • General
      • Add Ascent's core files as Additional Dependencies: ../../../../dep/include;../../../../dep/src/;../../../ascent-shared;../../../ascent-world
    • Preprocessor
      • Ensure that external symbols get resolved by adding _USRDLL;SCRIPTLIB to your Preprocessor Definitions.
    • Code Generation
      • Set Runtime Library to Multi-threaded Debug (/MTd) to avoid dependency on the .Net Framework.
    • Advanced
      • Finally you might want to diable the following warnings: 4793,4561,4996 (since those will come up a lot from the Ascent source).

Add the default files

Add a Setup.h and Setup.cpp file to the project containing the following:

Setup.h

// Setup.h: Contains declarations of functions that we want to use initially.
#pragma once // see http://en.wikipedia.org/wiki/Pragma_once

Setup.cpp

//Setup.cpp: At least contains the extern methods _exp_get_version, _exp_get_script_type and _exp_script_register
#include "../ascent-world/StdAfx.h"
#include "Setup.h"
//#include <scriptSetup.h> Required in rev 4000+

// this function is needed by Ascent to make sure that this lib is compatible with the Ascent version in use
extern "C" SCRIPT_DECL uint32 _exp_get_version() {
	return MAKE_SCRIPT_VERSION(SCRIPTLIB_VERSION_MAJOR, SCRIPTLIB_VERSION_MINOR);
}

// this function is called by Ascent so it knows what kind of addon this is
extern "C" SCRIPT_DECL uint32 _exp_get_script_type() {
	return SCRIPT_TYPE_MISC;
}

// this function is called by Ascent when loading the lib (at the end of the startup-routine)
extern "C" SCRIPT_DECL void _exp_script_register(ScriptMgr* mgr) {
	
}

Hello World

Lets make some tiny modifications to our default files:

Setup.h

// The Setup.h file: Contains declarations of functions that we want to use initially.

#pragma once // see http://en.wikipedia.org/wiki/Pragma_once

// declare the function (not required in this case but still...)
void sayHelloWorld();

Setup.cpp

//The Setup.cpp file: At least contains the extern methods _exp_get_version and _exp_script_register
#include "../ascent-world/StdAfx.h"
#include "Setup.h"

// the function that will do it!
void sayHelloWorld() {
	// Lets say Hello!
	// the sLog-object provides methods to make strings show up in the console and in log-files
	sLog.outString("\nHELLO WORLD!\n");
}

// this function is needed by Ascent to make sure that this lib is compatible with the Ascent version in use
extern "C" SCRIPT_DECL uint32 _exp_get_version() {
	return MAKE_SCRIPT_VERSION(SCRIPTLIB_VERSION_MAJOR, SCRIPTLIB_VERSION_MINOR);
}

// this function is called by Ascent so it knows what kind of addon this is
extern "C" SCRIPT_DECL uint32 _exp_get_script_type() {
	return SCRIPT_TYPE_MISC;
}

// this function is called by Ascent when loading the lib (at the end of the startup-routine)
extern "C" SCRIPT_DECL void _exp_script_register(ScriptMgr* mgr) {
	// call the function that will do something here (upon server-startup)
	sayHelloWorld();
}

Compile and Debug the code

It is highly recommended to debug every piece of code that you are running. This way you can use breakpoints and step through your code to find out what values certain variables have and why stuff doesn't work as expected.

  • Make sure that Ascent has been built with Debug-Configuration
  • Right-click the new Addon's Project (in the Solution Explorer) -> Set as StartUp Project
  • Right-click the Project -> Debug -> Start New Instance (that will build the addon and execute Ascent)
  • See how the lib compiles and Ascent starts


After a while we see the loading of custom libraries in Ascent and: Hooray! We greeted the world during the initilization of our custom Addon.






See Screenshot

What's next?

Try to Understand the Ascent Code and take a good look at Ascent's game-project and the other Addons that are already part of the scripts2008 - Solution to see what tools you have and how to use them.
Feel free to ask about and discuss your code at the code discussion forum.

Release

After you made sure that your code works, you can release it:

  • Make sure that Ascent has been built with Release-Configuration
  • Change the Addon's Configuration to Release
  • Build the Project
  • Done :)

Share

When you think, you created something of value which might also be useful to others, feel free to post it at the release forum and become a little famous.

Related links

Site Toolbox:

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