diff --git a/Core/GDCore/DocMainPage.h b/Core/GDCore/DocMainPage.h index 6b8f6e3c82..2f0f6e3d88 100644 --- a/Core/GDCore/DocMainPage.h +++ b/Core/GDCore/DocMainPage.h @@ -1,592 +1,25 @@ /** * \mainpage GDevelop Core * \image html gdlogo.png - * \section welcome Welcome + * \section welcome GDevelop Core documentation * - * The **GDevelop Core** library contains the main concepts, classes and tools that are used by the *platforms* and the *GDevelop IDE*.
- * This ensures that the IDE, or any tool based on GDevelop Core, is able to work with projects based on any arbitrary platform. - * - * Two official platforms are available for GDevelop: - * - The *C++ Platform* (GDCpp) to create native games. - * - The *JS Platform* (GDJS) to create HTML5 games. + * The **GDevelop Core** library contains the structure of a GDevelop game, classes and tools that are used by the *platforms* and the *GDevelop IDE*. * * \section gettingstarted Getting started - * First, please refer to these pages to install the required tools and to get help about setting up a basic extension:
* - * -# \subpage setupDevEnv - * -# \ref overview - * -# \ref writeANewExtension + * In most cases, you should start by installing and launching the development version of GDevelop. * - * You can also read \subpage recommendedToolsAndConventions. + * - If you're interested in writing extensions for GDevelop, read the documentation about extensions. + * - If you want to dig more into how GDevelop is architectured and work on the core, read GDevelop Architecture Overview. Then, you can browse this reference to get more information about a class or function. * - * \section aboutdoc About this documentation + * \section other Other documentations * - * If you never used GDevelop Core before, take a look at \ref overview. - * - * As everything that is developed around GDevelop is based on this library, you should take a look at it quite often: platforms, extensions - * and the IDE are intensively using the classes and tools offered by GDCore. - * When developing an extension for the C++ or JS platform, read these documentations: + * GDevelop is architectured around a `Core` (this library), platforms (`GDJS`, `GDCpp`) and extensions (`Extensions` folder). The editor (`newIDE` folder) is using all of these libraries. * * - [Open GDevelop C++ Platform documentation](../GDCpp Documentation/index.html) * - [Open GDevelop JS Platform documentation](../GDJS Documentation/index.html) - * - */ - -/** - * \page setupDevEnv Setting up the development environment - * - * If you didn't already downloaded GDevelop, get and extract the source from [GitHub](https://github.com/4ian/GD). - * - * Follow these steps to be able to compile GDevelop, it's super easy: - * - * Windows - * - * -# \subpage installWinCompiler - * -# \ref installAndUseCMake - *
- * - * GNU/Linux - * -# \subpage installLinuxLib - * -# \subpage installAndUseCMake - * - * OS X - * -# \subpage installMacOSTools - * -# \ref installAndUseCMake - * - * See the recommended tools and conventions for working on GDevelop on this page: - * \subpage recommendedToolsAndConventions - */ - -/** - * \page installWinCompiler (Windows) Install TDM-GCC compiler - * - * GDevelop is compiled with TDM-GCC under Windows.
- * So as to prevent incompatibilities between the compiler (and the standard C++ library provided with) used by GDevelop and - * the compiler used by the extensions, GDevelop require the extensions and the platforms to use the same version of TDM-GCC. - * - * While a recent GCC version should work, if you compile GDevelop for an "official" distribution it's better - * to use the specific version provided here. - * - * \section installWinCompiler_download Download - * - * Download the current version of the compiler used by GDevelop on Windows here: - * - * https://sourceforge.net/projects/tdm-gcc/files/TDM-GCC%20Installer/Previous/1.1309.0/tdm-gcc-4.9.2.exe/download - * - * \section installWinCompiler_install Installation - * - * The installation is fairly simple :
- *
- * - Launch the installer.
- * - Choose Create.
- - \image html compilerInstall1.png - - * - Choose an installation directory.
- - \image html compilerInstall2.png - - * - Choose the components to be installed. You don't have to change anything, the default options are good enough.
- - \image html compilerInstall3.png - - * - Click on install so as to launch the installation process.
- */ - -/** - * \page installAndUseCMake (All) Install CMake & launch the build - * - * Building is done using CMake: it is an open-source build system that can generate build files for lots of IDE and build tools (Makefiles...). - * - * \section installAndUseCMake_download Download and install CMake - * - * First, install CMake: - * Download it [here](http://www.cmake.org/cmake/resources/software.html) for Windows, get it using your package manager if you're - * using a Linux distribution or using Homebrew for Mac OS X. - * - * \section installAndUseCMake_use Using CMake to generate the build files - * Using CMake is not difficult and require only a few clicks/commands to enter. Windows users may use - * the GUI as shown in the next section. Linux and Mac OS X users may prefer to use the command line as shown - * as the end of this page. - * - * \subsection installAndUseCMake_use_gui Using the GUI - * - * - Start the CMake user interface (_cmake-gui_). Choose the GD root directory as the source directory, and Binaries/build as the directory where to build the binaries: - - \image html usecmake1.png - - * - Click on *Configure*. If asked to create the build directory, answer yes. Choose then your favorite generator: *MinGW Makefiles* (on Windows) or *Unix Makefiles* (on Linux/OS X) generate a traditional Makefile that can be built using the - * *mingw32-make* (on Windows) or *make* (on Linux/OS X) command. You can also choose the *Ninja* generator to use the [Ninja build system](http://martine.github.io/ninja/). - - \image html usecmake2.png - - * - When you click on Finish, CMake do a first configuration. If **errors occurred*, make sure that you have download all required development libraries. - * - Adjust any variable if necessary (no changes is needed by default), then click on Generate. - - \image html usecmake3.png - - * - You can then launch a terminal/command prompt, go to the build folder (`cd path/to/GD/Binaries/build`) and launch the build - * using the generator you've choosen: `mingw32-make`, or `make` on Linux/OS X. - * - * \subsection installAndUseCMake_use_cmd Using the command line - * - * Using the commandline with CMake is also easy: - * - * ~~~~~~~~~~~~~~~~~~~~~ - * cd /path/to/GD/Binaries - * mkdir build - * cd build - * cmake ../.. - * make - * ~~~~~~~~~~~~~~~~~~~~~ - * - * For Windows, replace `cmake ../..` by `cmake ../.. -G "MinGW Makefiles"` and `make` by `mingw32-make`. - * - * or using the fast [Ninja build system](http://martine.github.io/ninja/) : - * ~~~~~~~~~~~~~~~~~~~~~ - * cd /path/to/GD/Binaries - * mkdir build - * cd build - * cmake ../.. -G "Ninja" - * ninja - * ~~~~~~~~~~~~~~~~~~~~~ - * - * \section installAndUseCMake_launch Launch GDevelop - * - * Binaries are created into *Binaries/Output/Release_{OS}* folder. - * - * To launch GDevelop in Windows, double click on **GDIDE**. For Linux, launch **StartGDevelop.sh**. - */ - -/** - * \page installLinuxLib (Linux) Install development files - * - * \section installLibs Install development libraries - * - * GDevelop is compiled with gcc under Linux.
- * You need to have some packages to be installed before starting to build GD. These packages can vary according to the distribution you use. - * On Ubuntu, you may want to install these packages: -\code -sudo apt-get install libopenal-dev -sudo apt-get install libjpeg-dev -sudo apt-get install libglew-dev -sudo apt-get install libudev-dev -sudo apt-get install libxrandr-dev -sudo apt-get install libsndfile1-dev -sudo apt-get install libglu1-mesa-dev -sudo apt-get install libfreetype6-dev -\endcode - * Make sure you also have some basic tools installed: -\code -sudo apt-get install build-essential -sudo apt-get install p7zip-full -sudo apt-get install curl -\endcode - * - * If you want to package the app, you can also install: -\code -sudo apt-get install devscripts -\endcode - * - * - * \subsection installcmake Install CMake - * You'll need CMake to build GDevelop: See more on \subpage installAndUseCMake. - */ - -/** - * \page installMacOSTools (Mac OS X) Install development tools - * - * Make sure that you have Apple Developer Tools installed (if you have Xcode and git, that should be the case). - * - * \section installTools Install development tools - * - * The simplest way of installing dependencies required by GDevelop is to use [Homebrew](http://brew.sh/). Install it - * and install these packages, using the terminal: -\code -brew install cmake -brew install p7zip -brew install pkgconfig -brew install freetype -\endcode - * If you want to generate the documentation and translations, install Doxygen and Gettext: -\code -brew install doxygen -brew install gettext -\endcode - * - * \section launchCompilation Launch compilation - * - * You should be able to compile GD using CMake. Go with a terminal to the GD source folder: -\code -cd /path/to/GD -mkdir build && cd build -cmake ../.. -make -j4 -\endcode - * - * More information about compilation here: \ref installAndUseCMake - */ - - -/** - * \page recommendedToolsAndConventions Recommended tools and advices to work with GD - * - * \section git Git and GitHub - * - * Git is an amazing *version control system*. If you never used it before, take a look at some tutorials, there - * are plenty of them on the internet.
- * Windows users could be interested in using [TortoiseGit](code.google.com/p/tortoisegit) or the official - * [GitHub client](https://windows.github.com/). - * - * \subsection pullrequest Submitting code thanks to Pull Request. - * - * Using *Pull request*, you can easily submit your changes so that they are integrated into the official - * GDevelop repository (http://github.com/4ian/gd). - * - * See this article on *GitHub help* about pull requests: https://help.github.com/articles/using-pull-requests.
- * Pull requests are extremely easy to use and the best way to contribute to GD! - * - * ------ - * - * \section codingstyle Coding style - * - * As a rule of thumb, try to retain the original coding style used in a file when editing it, or look at other - * files when creating a new extension/dialog/feature/class. - * - * For both C++ and Javascript, *code indentation* should be 4 spaces (or tab set to a width of 4 spaces).
- * Lines should be cutted when reaching column 110 so that two files can be displayed side-by-side on a same screen. - * When cutting a line, indent the new lines with an additional 4 spaces. - * - * \subsection cpp C++ - * - * *Naming* conventions: - * - Classes should be *CamelCase* (starting with a capital). - * - All variables (including member variables) should be *camelCase* (no capital for the first letter). - * - All functions (including class methods) should be *CamelCase* (starting with a capital). - * - * *Comments*: - * - Comment your classes and functions using *Doxygen* comments. - * - * \subsection js Javascript - * - * *Naming* conventions: - * - "Classes" should be *CamelCase* (starting with a capital). - * - All variables (including member variables) should be *camelCase* (no capital for the first letter). - * - All functions (including class methods) should be *camelCase* (no capital for the first letter). - * - * *Comments*: - * - Comment your classes and functions using *yuidoc* comments. - */ - -/** - * \page overview Overview of GDCore - * - * \section platformstructure Structure of a platform - * - * A platform for GDevelop Core is a class inheriting from gd::Platform.
- * They contains the extensions of the platform (see below) and offer various methods, like gd::Platform::GetProjectExporters which - * is called by the IDE to export a gd::Project to a stand-alone game. - * - * \subsection platformloading Platforms loading - * A platform is stored in memory and managed by gd::PlatformManager. It loaded from a dynamic library file (.dll on windows, .so on Linux) - * thanks to gd::PlatformLoader.
- * It is responsibility of the IDE, or any other application using GDCore, - * to call the appropriate method of gd::PlatformLoader to trigger the loading of the platforms when needed. - * - * gd::PlatformLoader search for two symbols in the dynamic library file: *CreateGDPlatform* and - * *DestroyGDPlatform*. These symbols must exists and must create (or destroy) the platform class. For example: - * - * ~~~~~~~~~~~~~~~~~~~~~ - * extern "C" gd::Platform * GD_API CreateGDPlatform() { - * return &JsPlatform::Get(); //Return the singleton object representing the JS Platform - * } - * - * extern "C" void GD_API DestroyGDPlatform() { - * JsPlatform::DestroySingleton(); //Destroy the singleton. - * } - * ~~~~~~~~~~~~~~~~~~~~~ - * - * The platform dynamic library file is often located inside GDevelop directory/xxxPlatform (*xxx* being replaced by the platform acronym). - * - * In this folder, the platform can store basically anything it needs. For example, both GDJS and GDCpp are storing a folder called *Runtime* containing - * the game engine. - * If there is a sub directory called *Extensions*, the gd::PlatformLoader tries to load the extensions contained inside (see below). - * - * \section extensionsstructure Structure of an extension - * - * **Extensions** are seen by GDevelop Core as classes inheriting from gd::PlatformExtension.
- * They are stored inside the platform they belong to, and they are also loaded from a dynamic library file thanks to gd::ExtensionsLoader. The main - * job of an extension is to declare everything it provides: objects, actions and conditions, behaviors, expressions.
- * This is done directly using the standard method provided by gd::PlatformExtension, notably: - * - gd::PlatformExtension::AddCondition and gd::PlatformExtension::AddAction, - * - gd::PlatformExtension::AddExpression (and gd::PlatformExtension::AddStrExpression), - * - gd::PlatformExtension::AddObject and gd::PlatformExtension::AddBehavior - * - * - * Some platforms (like the C++ Platform) offer another base class which must be used instead of gd::PlatformExtension when declaring a platorm: as this base class - * inherits from gd::PlatformExtension, standard methods still work, but you may be able to declare some others features (the C++ Platform offers - * the possibility of declaring debugger related functions). - * - * \subsection extensionloading Extensions loading - * - * A single dynamic library file can contains an extension for more than one platform:
- * You just have to declare a class deriving from gd::PlatformExtension for each platform supported, and a creation function for each platform - * (the C++ platform expects a function called *CreateGDExtension* while JS Platform search for a function called *CreateGDJSExtension*). - * - * \subsection extensionexample Edit or write a new extension - * - * Refer to these pages for more information about extensions: - * - \subpage AboutExtensionCpp - * - \subpage writeANewExtension - * - * \section utf8section UTF8 strings - * - * Most parts of the codebase support UTF8 strings thanks to gd::String class. gd::String is a wrapper around std::string, exposing a similar - * interface as well as a few tool member functions and operators that are all UTF8 aware. - * - * Its usage is easy, especially if you're familiar with std::string. Some extra functions can be really useful, in particular - * the ones to convert the string from/to a number. - * - \code -gd::String str = "Hello"; -str += " world"; -str += " " + gd::String::From(2); -//str now contains "Hello world 2"; - -gd::String twopointfiveStr = "2.5"; -double twopointfive = twopointfive.To(); -//twopointfive == 2.5 - \endcode - * - * - * For more information, see the complete reference of the class. Tests cases have also been made for most functions. - */ - -/** - * \page writeANewExtension Write a new extension - * - * \section writeANewExtension_createNewExtension Create a new extension - * - * Creation of a new extension can be made by following these steps:
- * - * - Copy the directory of an extension and rename it: - * \image html createnew1.png - * - Rename then the sources files : - * \image html createnew2.png - * - Open the *CMakeLists.txt* file and replace every occurrence of the extension old name with the new name.
- * - Open all the source files and again, replace every occurrence of the extension old name with the new name.
- * - In the *Extensions* directory, open the *CMakeLists.txt* file and add a line such as ADD_SUBDIRECTORY(MyExtension). - * You can then start to modify the extension.
- * If your extension is fairly simple, you can create it from the AES Extension.
- * If your extension need an object, you can use for instance the TextObject Extension as a starting point.
- *
- * - You can compile your extension by relaunching CMake like described [here](\ref installAndUseCMake). After doing that, just compile as usual. - * - */ - -/** - * \page AboutExtensionCpp About Extension.cpp - * - * An extension has to define (usually in a file called *Extension.cpp* for the C++ Platform or *JsExtension.cpp* for the JS Platform) - * a class that is derived from the gd::PlatformExtension class. This class contains, in its constructor, the declarations - * of everything that is provided by the extension. - - * \section extensionDeclaration Declare the extension information - - * The declarations are made using the methods provided by gd::PlatformExtension. - * - * The first declaration if often the information about the extension: - - * \code - Extension() - { - SetExtensionInformation("TextObject", - _("Text object"), - _("Extension allowing to use an object displaying a text."), - "Florian Rival", - "Open Source (MIT License)"); - * \endcode - -The first parameter is the name of the extension. Choose carefully the name of the extension, as projects are directly referring to it. - - * \section instructionsDeclaration Declare actions, conditions and expressions - -Actions are declared like this : - - * \code - AddAction("ActionName", - _("Name displayed to users"), - _("Description"), - _("Sentence displayed in event editor"), - _("Category"), - "path-to-an-24-by-24-icon-file.png", - "path-to-an-16-by-16-icon-file.png") - .AddParameter("theTypeOfTheParameter", _("Parameter1")) - .AddParameter("theTypeOfTheParameter", _("Parameter2")) - .SetFunctionName("MyFunctionName").SetIncludeFile("MyExtension/MyIncludeFile.h"); - - * \endcode - * Declare conditions and expressions in a similar way.
- * Parameters are added using gd::InstructionMetadata::AddParameter. - * - * The last line set the function name that will be called when generating the code of an event using the action:
- * You can either do it after declaring the function, or later using this syntax: - * - * \code - GetAllActions()["ExtensionName::ActionName"].SetFunctionName("MyFunctionName"); - * \endcode - * - * Both methods are ok, but the latest allows to use the same code to declare an extension for the C++ and JS platform, - * then customize the names of the functions to call. - * - * \section objectsDeclaration Declare objects - * - * Adding an object is made using gd::PlatformExtension::AddObject method. - * - * \code - gd::ObjectMetadata & obj = AddObject( - "Name", - _("Name displayed to users"), - _("Description"), - "path-to-a-32-by-32-icon.png"); - * \endcode - * - * The *C++ platform* also requires that you call *AddRuntimeObject* to declare the RuntimeObject class associated to the object being declared:
- * It has two template parameters: the first one is the corresponding object class declared with *AddObject* (class inheriting from *gd::Object*) and the - * second one is the *RuntimeObject* class. - * You must pass as parameter the metadata from the object previously declared and the name of the class inheriting from RuntimeObject. - * - * You will also want to specify the .h file associated to the object using gd::ObjectMetadata::SetIncludeFile. For example: - * \code -//obj is the gd::ObjectMetadata returned when you called AddObject. -AddRuntimeObject(obj, "RuntimeTextObject"); -obj.SetIncludeFile("TextObject/TextObject.h"); - * \endcode - * - * You can then declare the actions, conditions, and expressions related to the objects, using the AddAction/AddCondition/AddExpression methods provided - * by obj. - - * \section eventsDeclaration Declaring events - * - * Events are declared like this : - * \code -AddEvent("Name", - _("Name displayed to users"), - "Description", - "Group", - "path-to-a-16-by-16-icon.png", - std::make_shared()) - * \endcode - * - * The event must be able to generate its code when events are being translated to C++ or Javascript:
- * This is done by calling SetCodeGenerator. For example: - * - * \code -AddEvent("Standard", - _("Standard event"), - _("Standard event: Actions are run if conditions are fulfilled."), - "", - "res/eventaddicon.png", - std::make_shared()) - .SetCodeGenerator(std::shared_ptr(codeGen)); - * \endcode - - * \section behaviorsDeclaration Declaring the behaviors - -Behaviors are declared like objects: - - - * \code -gd::BehaviorMetadata & aut = AddBehavior("Name", - _("Name displayed to users"), - _("DefaultNameUsedInEditor"), - _("Description."), - "Group", - "path-to-a-32-by-32-icon.png", - "BehaviorClassName", - std::make_shared(), - std::make_shared()); - * \endcode - * The last line can be replaced by std::shared_ptr() if no shared data are being used. - * - * You can then declare the actions, conditions, and expressions related to the behavior like objects:
- * Call AddAction/AddCondition/AddExpression on the aut object. - - * \section excludingNonRuntimeDeclaration (C++ platform) Excluding elements declaration from runtime - * When your extension is compiled for the C++ platform Runtime, GDevelop does not known anything about action/condition or even events classes.
- * You have then to exclude all actions/conditions/expressions/events declaration from extension at runtime (only Extension/Object/Behaviors declarations have to be kept). - - * Use the *GD_IDE_ONLY define* to achieve this goal, as demonstrated in this skeleton of a complete extension declaration: - * \code -class Extension : public ExtensionBase //For C++ platform, extensions must derive from ExtensionBase -{ -public: - Extension() - { - SetExtensionInformation("MyExtension", - _("Extension name"), - _("Extension declaration"), - "Author", - "license"); - - #if defined(GD_IDE_ONLY) - AddAction(...); - AddCondition(...); - AddExpression(...); - #endif - - { - gd::ObjectMetadata & obj = AddObject("ObjectName", - _("Object name"), - _("Description"), - "CppPlatform/Extensions/myicon.png", - &CreateMyObject, - &DestroyMyObject); - - AddRuntimeObject(obj, "RuntimeObjectName", CreateRuntimeObjectName); - - #if defined(GD_IDE_ONLY) - obj.SetIncludeFile("MyExtension/MyIncludeFile.h"); - - obj.AddAction(...); - obj.AddCondition(...); - obj.AddExpression(...); - #endif - - } - - { - gd::BehaviorMetadata & aut = AddBehavior("BehaviorName", - _("Behavior name"), - "defaultGDname", - _("Description"), - "", - "CppPlatform/Extensions/myicon.png", - "PhysicsBehavior", - std::make_shared(), - std::make_shared()); - - #if defined(GD_IDE_ONLY) - behaviorInfo.SetIncludeFile("MyExtension/MyIncludeFile.h"); - - aut.AddAction(...); - aut.AddCondition(...); - aut.AddExpression(...); - #endif - - } - - GD_COMPLETE_EXTENSION_COMPILATION_INFORMATION(); - }; - virtual ~Extension() {}; -}; - -// Used by GDevelop to create the extension class -// -- Do not need to be modified. -- -extern "C" ExtensionBase * GD_EXTENSION_API CreateGDExtension() { - return new Extension; -} - * \endcode + * - Getting started with the editor + * - Getting started with the extensions */ /** diff --git a/Core/GDevelop-Architecture-Overview.md b/Core/GDevelop-Architecture-Overview.md new file mode 100644 index 0000000000..6a2b8bd525 --- /dev/null +++ b/Core/GDevelop-Architecture-Overview.md @@ -0,0 +1,122 @@ +# GDevelop Architecture Overview + +GDevelop is architectured around a `Core` library, platforms (`GDJS`, `GDCpp`) and extensions (`Extensions` folder). The editor (`newIDE` folder) is using all of these libraries. This is a recap table of the main folders: + +| Directory | ℹī¸ Description | +| --- | --- | +| `Core` | GDevelop core library, containing common tools to implement the IDE and work with GDevelop games. | +| `GDCpp` | GDevelop C++ game engine, used to **build native games**. | +| `GDJS` | GDevelop JS game engine, used to build **HTML5 games**. | +| `GDevelop.js` | Bindings of Core/GDCpp/GDJS and Extensions to JavaScript (used by the IDE). | +| `newIDE` | The game editor, written in JavaScript with React, Electron and Pixi.js. | +| `Extensions` | Extensions for C++ or JS game engines, providing objects, events and new features. | + +The rest of this page is an introduction to the main concepts of GDevelop architecture. + +## Some vocabulary: "Runtime" and "IDE" + +**IDE** stands for "Integrated Development Environment". A synonym for it is also simply "editor". In GDevelop, the software itself, that is used to create games and running as an app or a web-app, is called the "GDevelop Editor" or the "GDevelop IDE" + +> This term "IDE" is also used in some folders. When you browse `Core`, `GDCpp` or `GDJS` subfolders, some folders are called `IDE`. They contain classes and tools that are **only useful for the editor** (they are not per se mandatory to describe the structure of a game). + +**Runtime** is a word used to describe classes, tools and source files being used during a game. This could also be called "in game" or a "game engine". + +> When you browse `GDCpp` or `GDJS` subfolders, you can find folders called `Runtime`. They contain the **game engine** of GDevelop. + +Extensions do have the same distinction between the "**IDE**" part and the "**Runtime**" part. For example, most extensions have: + +* A file called [`JsExtension.js`(https://github.com/4ian/GDevelop/blob/master/Extensions/ExampleJsExtension/JsExtension.js)], which contains the *declaration* of the extension for the **IDE** +* One or more files implementing the feature for the game, in other words for **Runtime**. This can be a [Runtime Object](https://github.com/4ian/GDevelop/blob/master/Extensions/ExampleJsExtension/dummyruntimeobject.js) or a [Runtime Behavior](https://github.com/4ian/GDevelop/blob/master/Extensions/ExampleJsExtension/dummyruntimebehavior.js), [functions called by actions or conditions](https://github.com/4ian/GDevelop/blob/master/Extensions/ExampleJsExtension/examplejsextensiontools.js) or by the game engine. + +### "Runtime" and "IDE" difference using an example: the `gd::Variable` class + +In GDevelop, developers can associate and manipulate variables in their games. To represent them, we have two things: + +* The **editor** `gd::Variable` that is part of the structure of the game, so living in [GDCore in Variable.h](https://4ian.github.io/GD-Documentation/GDCore%20Documentation/classgd_1_1_variable.html). This is what is shown in the editor, saved on disk in the project file. +* The **game engine** variable, called `gdjs.Variable` in GDJS. [Documentation is in the GDJS **game engine**](http://4ian.github.io/GD-Documentation/GDJS%20Runtime%20Documentation/gdjs.Variable.html). This JavaScript class is what is used during a game. + +The editor `gd::Variable` **know nothing** about the game engine class `gdjs.Variable`. And the `gdjs.Variable` class in the game engine know almost nothing from `gd::Variable` (apart from how it's written in JSON, to be able to load a game default variables). + +> Note that the name `gdjs.Variable` is maybe a *bad decision*: it should have been called a `gdjs.RuntimeVariable`, like `gdjs.RuntimeObject` and like most other classes of the game engine. + +## What's inside "Core" (`GDCore` folder)? + +GDevelop "Core" is basically containing everything that is used to **describe and manipulate the structure of a game** (called a `Project` internally). This includes events, scenes, objects, behaviors, events etc... All of these are implemented using C++ classes, in [this folder named `Project`](https://github.com/4ian/GDevelop/tree/master/Core/GDCore/Project). + +GDevelop "Core" also contains **tools** to manipulate these `Project`. In particular, `Core/GDCore/IDE` folder is containing C++ classes allowing to do operations on the structure of a game. For example, [WholeProjectRefactorer](https://github.com/4ian/GDevelop/blob/master/Core/GDCore/IDE/WholeProjectRefactorer.cpp) is a very powerful tool, used to rename all objects in a game, update events after an object is deleted and more generally do Project wide refactoring. The directory contains other "tool" functions to manipulate [resources of projects](https://github.com/4ian/GDevelop/tree/master/Core/GDCore/IDE/Project) or do [search in events](https://github.com/4ian/GDevelop/tree/master/Core/GDCore/IDE/Events). + +## What's inside GDJS? Why do I see some C++ file there? + +While `GDJS/Runtime` folder is the game engine that is executed inside a game, `GDJS/GDJS` is the "IDE" part, which are the C++ classes describing to the editor various things like: + +* How [do you do an export](https://github.com/4ian/GDevelop/tree/master/GDJS/GDJS/IDE), +* What are [the default extensions](https://github.com/4ian/GDevelop/tree/master/GDJS/GDJS/Extensions/Builtin), +* How do you [generate JS code from events](https://github.com/4ian/GDevelop/tree/master/GDJS/GDJS/Events/CodeGeneration), + +The game engine is in GDJS/Runtime and is all JavaScript. + +## What about events? + +An "**event**" is by default something that [is mostly empty](http://4ian.github.io/GD-Documentation/GDCore%20Documentation/classgd_1_1_base_event.html). In a more traditional programming language, an event can be seen as a scope or block (example: `{ some code here }` in a C style language like JavaScript, Java or C++). + +[Default events are defined](https://github.com/4ian/GDevelop/tree/master/Core/GDCore/Events/Builtin) in GDevelop Core. +In particular, there is StandardEvent, which has conditions and actions. Conditions and actions are both a list of [`gd::Instruction`](https://4ian.github.io/GD-Documentation/GDCore%20Documentation/classgd_1_1_instruction.html). A `gd::Instruction` is either a condition or an action (it depends only on the context where they are used). + +A `gd::Instruction` is "just" a type (the name of the action or condition), and some parameters. You can think of it as a function in a programming language (`add(2, 3)` is calling a function called "add" with parameter "2" and "3"). Conditions have the special thing that they are functions returning true or false (and potentially being used to do filter on the objects being picked for next conditions and actions). + +### Why can't I see any "RuntimeEvent" or events during the game? + +They do not exist anymore! ✨ + +Events are translated (we also say "transpiled" or "generated") into "real" code in a programming language. This process is called "Code Generation", and is [done here for the JavaScript game engine](https://github.com/4ian/GDevelop/tree/master/GDJS/GDJS/Events/CodeGeneration). + +### Can I extract Events classes and code generator to make a development environment based on GDevelop events? + +You're welcome to do so! Please get in touch :) + +## I can see more than one Extensions folder, why? + +The idea of GDevelop editor and game engine is to have a lean game engine, supporting almost nothing. Then, one can add "mods", "plugins", "modules" for GDevelop. We chose to call them "**Extensions**" in GDevelop. + +* `GDevelop/Core/GDCore/Extensions` is the **declaration** of default (we say "builtin") extensions, that are available for any game and are "mandatory". They are called Extensions but they could be named "Extensions that will always be in your game". In programming languages, this is called a "[Standard Library](https://en.wikipedia.org/wiki/Standard_library)" (but don't get too distracted by this naming). +* `GDevelop/GDJS/GDJS/Extensions/` and `GDevelop/GDCpp/GDCpp/Extensions/` are reusing these **declarations** and **adding** their own declarations. Mainly, they are setting the name of the functions to be called (either in JS or in C++) for each action, condition or expression. +* `GDevelop/Extensions/` is the folder for the "mods"/"plugins" for GDevelop - the one that are not mandatory. They are not part of GDCore - they work on their own. + +> In theory, all extensions could be moved to `GDevelop/Extensions/`. In practice, it's more pragmatic to have a set of "builtin" extensions with basic features. + +## What's GDevelop.js? Do we care about this? + +Everything in GDevelop.js is meant to create a "bridge" allowing to run and use C++ from JavaScript for the **IDE**, so that [we can write an editor entirely in JavaScript](https://github.com/4ian/GDevelop/tree/master/newIDE) and have it working in a web browser. + +* We're using Emscripten which is compiling C++, but instead of writing a "native binary", it's writing a file that works in a browser (basically, JavaScript!). + +* The most useful file is [Bindings.idl](https://github.com/4ian/GDevelop/blob/master/GDevelop.js/Bindings/Bindings.idl) that is describing everything in C++ that must be exposed to JavaScript (in the editor, not in game. Remember that during the game, we're at **Runtime**, so all of this does not exist anymore) + +* Rest of the files are mostly bridges doing "weird stuff" to translate from JS to C++ or vice versa. It requires a bit of knowledge about how the ["bridge", made by Emscripten, called WebIDL](https://emscripten.org/docs/porting/connecting_cpp_and_javascript/WebIDL-Binder.html) is working. + + You don't need to work with these unless you want to expose something that is written in C++ to the editor, and writing the interface in Bindings.idl is not sufficient. + +90% of the time, you can just read or write about a class in [Bindings.idl](https://github.com/4ian/GDevelop/blob/master/GDevelop.js/Bindings/Bindings.idl). If you work in C++ classes, you may have sometime to add a header file in Wrapper.cpp and your C++ class is "automagically" compiled and available in JavaScript after writing the corresponding interface in Bindings.idl. + +### I want all the gory details about GDevelop.js 🧐 + +All the required C++ files are imported into this huge list: https://github.com/4ian/GDevelop/blob/master/GDevelop.js/Bindings/Wrapper.cpp#L1-L79. C++ compilation is done with a "build system" called CMake, which is using [this file](https://github.com/4ian/GDevelop/blob/master/GDevelop.js/CMakeLists.txt#L82-L101) to see what to compile. + +> In an ideal world, there would be something to do this automatically, so GDevelop.js folder would not even exist 😉 +> If you're interested and want to know more about GDevelop.js bridging between C++ and JavaScript, look at [this talk from GDevelop original author](https://www.youtube.com/watch?v=6La7jSCnYyk). + +## Misc questions + +### What's the deal with C++? Why so much of it? + +GDevelop was originally written in C++. It's a scary language at first but is portable across almost any existing machine in this universe, can be pretty good, safe and readable with the latest C++ features. + +### What's the deal with JavaScript? Why so much of it? + +JavaScript, with the latest language proposals, is actually a very capable language, fast to write and safe with typing: + +* Performance is getting pretty good with recent browsers JIT features. +* Frontend frameworks like React, used for GDevelop IDE, allow for very fast and modular interface development. +* The web is an incredible and unmatched target when it comes to cross platform (and cross form factor) apps. + +More generally, the web is a great target for games with the rise of WebGL and WebAssembly - though GDevelop should stay modular to adapt to newer platforms for the exported games in the future. diff --git a/Readme.md b/Readme.md index b05b9d41f5..b50eb4b975 100644 --- a/Readme.md +++ b/Readme.md @@ -23,10 +23,10 @@ Overview of the architecture | `GDCpp` | GDevelop C++ game engine, used to **build native games**. | | `GDJS` | GDevelop JS game engine, used to build **HTML5 games**. | | `GDevelop.js` | Bindings of Core/GDCpp/GDJS and Extensions to JavaScript (used by the IDE). | -| `newIDE` | The game editor, written in Javascript with React, Electron and Pixi.js. | +| `newIDE` | The game editor, written in JavaScript with React, Electron and Pixi.js. | | `Extensions` | Extensions for C++ or JS game engines, providing objects, events and new features. | -### Documentation +To learn more about GDevelop Architecture, read the [architecture overview here](Core/GDevelop-Architecture-Overview.md). A pre-generated documentation of the Core library, C++ and JS game engines is [available here](http://4ian.github.io/GD-Documentation). diff --git a/scripts/GenerateAllDocs.sh b/scripts/GenerateAllDocs.sh index 8acb93285f..cba9788aad 100755 --- a/scripts/GenerateAllDocs.sh +++ b/scripts/GenerateAllDocs.sh @@ -1,6 +1,7 @@ #Script launching the generation of the documentations of all modules #Install globally doxgen and jsdoc before starting it. echo Generating all docs... +mkdir -p ../docs mkdir -p logs cd .. cd Core/docs