Relintai/pandemonium_engine_docs
1
0
Fork 0
mirror of https://github.com/Relintai/pandemonium_engine_docs.git synced 2025-01-04 14:49:52 +01:00
Code Issues Packages Projects Releases Wiki Activity

Fix inconsistencies.

Browse Source
This commit is contained in:
Relintai 2024-05-04 14:24:30 +02:00
parent 5dd773971a
commit 3007ff2b03
4 changed files with 163 additions and 161 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
03_usage/15_scripting/gdscript/01_gdscript_basics.md
View File

@ -650,15 +650,15 @@ Functions can also have type specification for the arguments and for the return
value. Types for arguments can be added in a similar way to variables value. Types for arguments can be added in a similar way to variables
``` ```
func my_function(a: int, b: String): func my_function(a: int, b: String):
pass pass
``` ```
If a function argument has a default value, it's possible to infer the type If a function argument has a default value, it's possible to infer the type
``` ```
func my_function(int_arg := 42, String_arg := "string"): func my_function(int_arg := 42, String_arg := "string"):
pass pass
``` ```
The return type of the function can be specified after the arguments list using The return type of the function can be specified after the arguments list using

308
05_engine_development/02_cpp/07_custom_modules_in_cpp.md
View File

@ -40,67 +40,68 @@ The example module will be called "summator" (`pandemonium/modules/summator`).
Inside we will create a simple summator class: Inside we will create a simple summator class:
``` ```
/* summator.h */ /* summator.h */
#ifndef SUMMATOR_H #ifndef SUMMATOR_H
#define SUMMATOR_H #define SUMMATOR_H
#include "core/reference.h" #include "core/reference.h"
class Summator : public Reference { class Summator : public Reference {
GDCLASS(Summator, Reference); GDCLASS(Summator, Reference);
int count; int count;
protected: protected:
static void _bind_methods(); static void _bind_methods();
public: public:
void add(int p_value); void add(int p_value);
void reset(); void reset();
int get_total() const; int get_total() const;
Summator(); Summator();
}; };
#endif // SUMMATOR_H #endif // SUMMATOR_H
``` ```
And then the cpp file. And then the cpp file.
``` ```
/* summator.cpp */ /* summator.cpp */
#include "summator.h" #include "summator.h"
void Summator::add(int p_value) { void Summator::add(int p_value) {
count += p_value; count += p_value;
} }
void Summator::reset() { void Summator::reset() {
count = 0; count = 0;
} }
int Summator::get_total() const { int Summator::get_total() const {
return count; return count;
} }
void Summator::_bind_methods() { void Summator::_bind_methods() {
ClassDB::bind_method(D_METHOD("add", "value"), &Summator::add); ClassDB::bind_method(D_METHOD("add", "value"), &Summator::add);
ClassDB::bind_method(D_METHOD("reset"), &Summator::reset); ClassDB::bind_method(D_METHOD("reset"), &Summator::reset);
ClassDB::bind_method(D_METHOD("get_total"), &Summator::get_total); ClassDB::bind_method(D_METHOD("get_total"), &Summator::get_total);
} }
Summator::Summator() { Summator::Summator() {
count = 0; count = 0;
} }
```
Then, the new class needs to be registered somehow, so two more files Then, the new class needs to be registered somehow, so two more files
need to be created: need to be created:
``` ```
register_types.h register_types.h
register_types.cpp register_types.cpp
``` ```
.. important: .. important:
@ -110,47 +111,47 @@ need to be created:
These files should contain the following: These files should contain the following:
``` ```
/* register_types.h */ /* register_types.h */
void register_summator_types(); void register_summator_types();
void unregister_summator_types(); void unregister_summator_types();
/* yes, the word in the middle must be the same as the module folder name */ /* yes, the word in the middle must be the same as the module folder name */
``` ```
``` ```
/* register_types.cpp */ /* register_types.cpp */
#include "register_types.h" #include "register_types.h"
#include "core/class_db.h" #include "core/class_db.h"
#include "summator.h" #include "summator.h"
void register_summator_types() { void register_summator_types() {
ClassDB::register_class<Summator>(); ClassDB::register_class<Summator>();
} }
void unregister_summator_types() { void unregister_summator_types() {
// Nothing to do here in this example. // Nothing to do here in this example.
} }
``` ```
Next, we need to create a `SCsub` file so the build system compiles Next, we need to create a `SCsub` file so the build system compiles
this module: this module:
``` ```
# SCsub # SCsub
Import('env') Import('env')
env.add_source_files(env.modules_sources, "*.cpp") # Add all cpp files to the build env.add_source_files(env.modules_sources, "*.cpp") # Add all cpp files to the build
``` ```
With multiple sources, you can also add each file individually to a Python With multiple sources, you can also add each file individually to a Python
string list: string list:
``` ```
src_list = ["summator.cpp", "other.cpp", "etc.cpp"] src_list = ["summator.cpp", "other.cpp", "etc.cpp"]
env.add_source_files(env.modules_sources, src_list) env.add_source_files(env.modules_sources, src_list)
``` ```
This allows for powerful possibilities using Python to construct the file list This allows for powerful possibilities using Python to construct the file list
@ -161,8 +162,8 @@ To add include directories for the compiler to look at you can append it to the
environment's paths: environment's paths:
``` ```
env.Append(CPPPATH=["mylib/include"]) # this is a relative path env.Append(CPPPATH=["mylib/include"]) # this is a relative path
env.Append(CPPPATH=["#myotherlib/include"]) # this is an 'absolute' path env.Append(CPPPATH=["#myotherlib/include"]) # this is an 'absolute' path
``` ```
If you want to add custom compiler flags when building your module, you need to clone If you want to add custom compiler flags when building your module, you need to clone
@ -170,30 +171,30 @@ If you want to add custom compiler flags when building your module, you need to
Example `SCsub` with custom flags: Example `SCsub` with custom flags:
``` ```
# SCsub # SCsub
Import('env') Import('env')
module_env = env.Clone() module_env = env.Clone()
module_env.add_source_files(env.modules_sources, "*.cpp") module_env.add_source_files(env.modules_sources, "*.cpp")
# Append CCFLAGS flags for both C and C++ code. # Append CCFLAGS flags for both C and C++ code.
module_env.Append(CCFLAGS=['-O2']) module_env.Append(CCFLAGS=['-O2'])
# If you need to, you can: # If you need to, you can:
# - Append CFLAGS for C code only. # - Append CFLAGS for C code only.
# - Append CXXFLAGS for C++ code only. # - Append CXXFLAGS for C++ code only.
``` ```
And finally, the configuration file for the module, this is a simple And finally, the configuration file for the module, this is a simple
python script that must be named `config.py`: python script that must be named `config.py`:
``` ```
# config.py # config.py
def can_build(env, platform): def can_build(env, platform):
return True return True
def configure(env): def configure(env):
pass pass
``` ```
The module is asked if it's OK to build for the specific platform (in The module is asked if it's OK to build for the specific platform (in
@ -203,12 +204,12 @@ And that's it. Hope it was not too complex! Your module should look like
this: this:
``` ```
pandemonium/modules/summator/config.py pandemonium/modules/summator/config.py
pandemonium/modules/summator/summator.h pandemonium/modules/summator/summator.h
pandemonium/modules/summator/summator.cpp pandemonium/modules/summator/summator.cpp
pandemonium/modules/summator/register_types.h pandemonium/modules/summator/register_types.h
pandemonium/modules/summator/register_types.cpp pandemonium/modules/summator/register_types.cpp
pandemonium/modules/summator/SCsub pandemonium/modules/summator/SCsub
``` ```
You can then zip it and share the module with everyone else. When You can then zip it and share the module with everyone else. When
@ -225,12 +226,12 @@ Note:
You can now use your newly created module from any script: You can now use your newly created module from any script:
``` ```
var s = Summator.new() var s = Summator.new()
s.add(10) s.add(10)
s.add(20) s.add(20)
s.add(30) s.add(30)
print(s.get_total()) print(s.get_total())
s.reset() s.reset()
``` ```
The output will be `60`. The output will be `60`.
@ -274,8 +275,8 @@ So if you feel like the independent structure of custom modules is needed, lets
take our "summator" module and move it to the engine's parent directory: take our "summator" module and move it to the engine's parent directory:
``` ```
mkdir ../modules mkdir ../modules
mv modules/summator ../modules mv modules/summator ../modules
``` ```
Compile the engine with our module by providing `custom_modules` build option Compile the engine with our module by providing `custom_modules` build option
@ -283,7 +284,7 @@ which accepts a comma-separated list of directory paths containing custom C++
modules, similar to the following: modules, similar to the following:
``` ```
scons custom_modules=../modules scons custom_modules=../modules
``` ```
The build system shall detect all modules under the `../modules` directory The build system shall detect all modules under the `../modules` directory
@ -325,41 +326,41 @@ The solution to avoid such a cost is to build our own module as a shared
library that will be dynamically loaded when starting our game's binary. library that will be dynamically loaded when starting our game's binary.
``` ```
# SCsub # SCsub
Import('env') Import('env')
sources = [ sources = [
"register_types.cpp", "register_types.cpp",
"summator.cpp" "summator.cpp"
] ]
# First, create a custom env for the shared library. # First, create a custom env for the shared library.
module_env = env.Clone() module_env = env.Clone()
# Position-independent code is required for a shared library. # Position-independent code is required for a shared library.
module_env.Append(CCFLAGS=['-fPIC']) module_env.Append(CCFLAGS=['-fPIC'])
# Don't inject Pandemonium's dependencies into our shared library. # Don't inject Pandemonium's dependencies into our shared library.
module_env['LIBS'] = [] module_env['LIBS'] = []
# Define the shared library. By default, it would be built in the module's # Define the shared library. By default, it would be built in the module's
# folder, however it's better to output it into `bin` next to the # folder, however it's better to output it into `bin` next to the
# Pandemonium binary. # Pandemonium binary.
shared_lib = module_env.SharedLibrary(target='#bin/summator', source=sources) shared_lib = module_env.SharedLibrary(target='#bin/summator', source=sources)
# Finally, notify the main build environment it now has our shared library # Finally, notify the main build environment it now has our shared library
# as a new dependency. # as a new dependency.
# LIBPATH and LIBS need to be set on the real "env" (not the clone) # LIBPATH and LIBS need to be set on the real "env" (not the clone)
# to link the specified libraries to the Pandemonium executable. # to link the specified libraries to the Pandemonium executable.
env.Append(LIBPATH=['#bin']) env.Append(LIBPATH=['#bin'])
# SCons wants the name of the library with it custom suffixes # SCons wants the name of the library with it custom suffixes
# (e.g. ".x11.tools.64") but without the final ".so". # (e.g. ".x11.tools.64") but without the final ".so".
shared_lib_shim = shared_lib[0].name.rsplit('.', 1)[0] shared_lib_shim = shared_lib[0].name.rsplit('.', 1)[0]
env.Append(LIBS=[shared_lib_shim]) env.Append(LIBS=[shared_lib_shim])
``` ```
Once compiled, we should end up with a `bin` directory containing both the Once compiled, we should end up with a `bin` directory containing both the
@ -368,8 +369,8 @@ a standard directory (like `/usr/lib`), we have to help our binary find it
during runtime with the `LD_LIBRARY_PATH` environment variable: during runtime with the `LD_LIBRARY_PATH` environment variable:
``` ```
export LD_LIBRARY_PATH="$PWD/bin/" export LD_LIBRARY_PATH="$PWD/bin/"
./bin/pandemonium* ./bin/pandemonium*
``` ```
Note: Note:
@ -383,29 +384,29 @@ module as shared library (for development) or as a part of the Pandemonium binar
using the `ARGUMENT` command: using the `ARGUMENT` command:
``` ```
# SCsub # SCsub
Import('env') Import('env')
sources = [ sources = [
"register_types.cpp", "register_types.cpp",
"summator.cpp" "summator.cpp"
] ]
module_env = env.Clone() module_env = env.Clone()
module_env.Append(CCFLAGS=['-O2']) module_env.Append(CCFLAGS=['-O2'])
if ARGUMENTS.get('summator_shared', 'no') == 'yes': if ARGUMENTS.get('summator_shared', 'no') == 'yes':
# Shared lib compilation # Shared lib compilation
module_env.Append(CCFLAGS=['-fPIC']) module_env.Append(CCFLAGS=['-fPIC'])
module_env['LIBS'] = [] module_env['LIBS'] = []
shared_lib = module_env.SharedLibrary(target='#bin/summator', source=sources) shared_lib = module_env.SharedLibrary(target='#bin/summator', source=sources)
shared_lib_shim = shared_lib[0].name.rsplit('.', 1)[0] shared_lib_shim = shared_lib[0].name.rsplit('.', 1)[0]
env.Append(LIBS=[shared_lib_shim]) env.Append(LIBS=[shared_lib_shim])
env.Append(LIBPATH=['#bin']) env.Append(LIBPATH=['#bin'])
else: else:
# Static compilation # Static compilation
module_env.add_source_files(env.modules_sources, sources) module_env.add_source_files(env.modules_sources, sources)
``` ```
Now by default `scons` command will build our module as part of Pandemonium's binary Now by default `scons` command will build our module as part of Pandemonium's binary
@ -415,7 +416,7 @@ Finally, you can even speed up the build further by explicitly specifying your
shared module as target in the SCons command: shared module as target in the SCons command:
``` ```
scons summator_shared=yes platform=x11 bin/libsummator.x11.tools.64.so scons summator_shared=yes platform=x11 bin/libsummator.x11.tools.64.so
``` ```
## Writing custom documentation ## Writing custom documentation
@ -434,13 +435,13 @@ There are several steps in order to setup custom docs for the module:
2. Now, we need to edit `config.py`, add the following snippet: 2. Now, we need to edit `config.py`, add the following snippet:
``` ```
def get_doc_path(): def get_doc_path():
return "doc_classes" return "doc_classes"
def get_doc_classes(): def get_doc_classes():
return [ return [
"Summator", "Summator",
] ]
``` ```
The `get_doc_path()` function is used by the build system to determine The `get_doc_path()` function is used by the build system to determine
@ -461,20 +462,20 @@ Tip:
untracked files with `git status`. For example: untracked files with `git status`. For example:
``` ```
user@host:~/pandemonium$ git status user@host:~/pandemonium$ git status
``` ```
Example output: Example output:
``` ```
Untracked files: Untracked files:
(use "git add <file>..." to include in what will be committed) (use "git add <file>..." to include in what will be committed)
doc/classes/MyClass2D.xml doc/classes/MyClass2D.xml
doc/classes/MyClass4D.xml doc/classes/MyClass4D.xml
doc/classes/MyClass5D.xml doc/classes/MyClass5D.xml
doc/classes/MyClass6D.xml doc/classes/MyClass6D.xml
... ...
``` ```
3. Now we can generate the documentation: 3. Now we can generate the documentation:
@ -488,7 +489,7 @@ to an another folder, and just copy over the files that you need.
Run command: Run command:
``` ```
user@host:~/pandemonium/bin$ ./bin/<pandemonium_binary> --doctool . user@host:~/pandemonium/bin$ ./bin/<pandemonium_binary> --doctool .
``` ```
Now if you go to the `pandemonium/modules/summator/doc_classes` folder, you will see Now if you go to the `pandemonium/modules/summator/doc_classes` folder, you will see
@ -512,8 +513,8 @@ Note that if you don't have write access rights to your supplied `<path>`,
you might encounter an error similar to the following: you might encounter an error similar to the following:
``` ```
ERROR: Can't write doc file: docs/doc/classes/@GDScript.xml ERROR: Can't write doc file: docs/doc/classes/@GDScript.xml
At: editor/doc/doc_data.cpp:956 At: editor/doc/doc_data.cpp:956
``` ```
## Adding custom editor icons ## Adding custom editor icons
@ -538,8 +539,8 @@ If you'd like to store your icons somewhere else within your module,
add the following code snippet to `config.py` to override the default path: add the following code snippet to `config.py` to override the default path:
``` ```
def get_icons_path(): def get_icons_path():
return "path/to/icons" return "path/to/icons"
``` ```
## Summing up ## Summing up
@ -561,3 +562,4 @@ some (hopefully positive) surprises.
saved/loaded. saved/loaded.
- By this same logic, you can extend the Editor and almost any area of - By this same logic, you can extend the Editor and almost any area of
the engine. the engine.
``````

6
06_community/contributing/15_contributing_to_the_documentation.md
View File

@ -156,7 +156,7 @@ To add images, please put them in an `img/` folder next to the `.rst` file with
a meaningful name and include them in your page with: a meaningful name and include them in your page with:
``` ```
![](img/image_name.png) ![](img/image_name.png)
``` ```
Similarly, you can include attachments, like assets as support material for a Similarly, you can include attachments, like assets as support material for a
@ -164,7 +164,7 @@ tutorial, by placing them into a `files/` folder next to the `.rst` file, and
using this inline markup: using this inline markup:
``` ```
:download:`myfilename.zip ( files/myfilename.zip )` :download:`myfilename.zip ( files/myfilename.zip )`
``` ```
## License ## License
@ -176,4 +176,4 @@ attribution to "Péter Magyar and the Pandemonium community, and Juan Linietsky,
By contributing to the documentation on the GitHub repository, you agree that By contributing to the documentation on the GitHub repository, you agree that
your changes are distributed under this license. your changes are distributed under this license.
``` ``````

2
06_community/contributing/17_documentation_guidelines.md
View File

@ -133,4 +133,4 @@ the `Creative Commons Attribution 3.0 license (CC-BY-3.0) ( https://tldrlegal.co
By contributing to the documentation on the GitHub repository, you agree that By contributing to the documentation on the GitHub repository, you agree that
your changes are distributed under this license. your changes are distributed under this license.
``` ``````