Differences

This shows you the differences between two versions of the page.

Link to this comparison view

gdevelop:documentation:manual:use_cpp [2015/05/18 12:28] (current)
Line 1: Line 1:
 +====== Using C++ and other experimental features =====
 +
 +<note warning>​This feature is experimental and only available for debugging purposes.</​note>​
 +
 +Events and built-in features offer powerful creation capabilities. For more complex needs, **GDevelop** allows to use C++ directly inside your projects.
 +You can benefit from the power of C++ to rewrite events, use algorithms or already existing code, mix events and programming or simply use GDevelop as an integrated development environment (IDE).
 +
 +===== Basics =====
 +
 +C++ code needs to be included in an object inheriting from the **BasEvent** class. This object has to be declared in the declaration file. You can invoke the code through a C++ event with the same name as the one entered in the declaration file.
 +
 +Before previewing a scene, GDevelop will re-compile the code modified since the last preview.
 +
 +===== Setup =====
 +
 +Before using C++ in a project, you have to set it up in GDevelop.
 +
 +==== Project setup ====
 +
 +Activate C++ in the project main parameters: go to the **//C++ sources//** tab and tick the relevant box.
 +**GDevelop** can create the basic files if the project does not contain any yet.
 +
 +==== Setting up GDevelop ====
 +
 +If you have never used C++ features before, or if you just installed a new version of GDevelop, you have to download supplementary files, extract them and tell GDevelop where they are located. Open **//​Options//​** in **GDevelop** from the //​**General**//​ ribbon or from the project main parameters, go to the **//C++ sources//** tab, click on **//​Configure GDevelop to use C++ sources files//**.
 +
 +A window will pop up and invite you to download a file from GDevelop website. Click on the link to start the download. Extract the file with a program like 7zip (http://​www.7-zip.org/​download.html). Finally, select the directory where the file have been extracted.
 +
 +Repeat these steps for each file.
 +
 +Click on **//Ok//** to close the window. **GDevelop** will inform you if a file seems to be invalid.
 +
 +===== Declaration file =====
 +
 +You can add a declaration file to your project using the menu element **//​Creating a new C++ file//**.
 +A declaration file looks like this:
 +
 +<​code>​
 +#include "​GDL/​DynamicExtensionBase.h"​
 +#include "​GDL/​Event.h"​
 +#include "​GDL/​RuntimeScene.h"​
 +#include "​GDL/​ObjectsConcerned.h"​
 +//Add here header file of your events
 +#include "​FichierEvent.h"​
 +
 +class DynamicExtension : public DynamicExtensionBase
 +{
 +    public:
 +
 +        DynamicExtension()
 +        {
 +            //Declare here your custom events. Don't forget to add headers files.
 +  //Custom C++ events can be created using "​Creating a new C++ file".
 +            callableEvents["​MyEvent"​] = boost::​shared_ptr<​BaseEvent>​(new MyEvent);
 +        };
 +        virtual ~DynamicExtension() {};
 +};
 +
 +/**
 + * Used internally by GDevelop
 + */
 +extern "​C"​ DynamicExtensionBase * CreateGDDynamicExtension() { return new DynamicExtension;​ }
 +
 +/**
 + * Used internally by GDevelop
 + */
 +extern "​C"​ void DestroyGDDynamicExtension(DynamicExtensionBase * p) { delete p; }
 +
 +
 +Grayed area does not require your attention.
 +To declare your custom C++ events, add a line in the DynamicExtension constructor :
 +
 +callableEvents["​NameUsedInGameDevelopEvents"​] = boost::​shared_ptr<​BaseEvent>​(new C++ObjectName);​
 +
 +You have to add the header of your events at the top of the file :
 +
 +#include "​HeaderFileOfYourEvent.h"</​code>​
 +
 +===== Event file =====
 +
 +In order to use some code, you will have to insert it into a C++ event. These events are objects, usually consisting of a header and an implementation file:
 +
 +Header file:
 +<​code>​
 +#include "​GDL/​Event.h"​
 +#include "​GDL/​RuntimeScene.h"​
 +#include "​GDL/​ObjectsConcerned.h"​
 +
 +/**
 + * Class of the event. Event can be customized by changing the Execute member function.
 + * You have to declare the event in the Declaration file to make it visible for GDevelop.
 + */
 +class MyEvent : public BaseEvent
 +{
 +public:
 +     ​virtual void Execute( RuntimeScene & scene, ObjectsConcerned & objectsConcerned );
 +};</​code>​
 +
 +
 +Implementation file:
 +<​code>​
 +#include "​GDL/​Event.h"​
 +#include "​GDL/​RuntimeScene.h"​
 +#include "​GDL/​ObjectsConcerned.h"​
 +#include "​EventFile.h"​
 +
 +void MyEvent::​Execute( RuntimeScene & scene, ObjectsConcerned & objectsConcerned )
 +{
 +     //You can insert here your C++ code.
 +}</​code>​
 +
 +Code that will be called must be put in the Execute member function. Each C++ event need a specific name, as every C++ object.
 +
 +In order to launch a C++ event, declare the latter in the declaration file, specifying the object name and the name that will be used by GDevelop events.
 +
 +===== Compilation inside GDevelop =====
 +
 +When a scene is about to be previewed, GDevelop will compile if needed source files.
 +
 +To display progress, display first C++ tools from the ribbon :
 +
 +
 +
 +Progress can be viewed in the Compilation tab. You can use this tab to stop the compilation.
 +
 +
 +
 +If compilation failed, GDevelop will open the concerned file and the tab Compilation messages, displaying errors in red.
 +Correct the errors and relaunch a scene preview to relaunch compilation.