Relintai/pandemonium_engine_docs
1
0
Fork 0
mirror of https://github.com/Relintai/pandemonium_engine_docs.git synced 2025-04-11 21:12:05 +02:00
Code Issues Packages Projects Releases Wiki Activity

Cleanups.

Browse Source
This commit is contained in:
Relintai 2024-05-04 00:04:16 +02:00
parent ad8f5a11a4
commit 8e87dc1fe7
105 changed files with 692 additions and 1871 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
03_usage/21_assets_pipeline/01_import_process.md
View File

@ -1,10 +1,7 @@
# Import process
Import process
==============
Importing assets in Pandemonium 3.0+
------------------------------
## Importing assets in Pandemonium 3.0+
Previously, importing assets in Pandemonium 2.x required manual maintenance
of a separate directory with source assets. Without doing this, it was
@ -26,8 +23,7 @@ it will work in the editor, but break in the exported project.
However, the `Resource Loader( ResourceLoader )` cannot access
non imported files, only the `File` class can.
Changing import parameters
--------------------------
## Changing import parameters
To change the import parameters of an asset in Pandemonium (again, keep in mind
import parameters are only present in non-native Pandemonium resource types)
@ -42,8 +38,7 @@ Changing the import parameters of several assets at the same time is also
possible. Simply select all of them together in the resources dock and the
exposed parameters will apply to all of them when reimporting.
Reimporting multiple assets
---------------------------
## Reimporting multiple assets
While working on a project you may find that several assets need to have
the same parameters changed, such as enabling mipmaps, but you only want
@ -58,15 +53,13 @@ assets, then change the parameters normally. Finally, click the reimport
button and every selected asset will be reimported with only those
parameters changed.
Automatic reimport
------------------
## Automatic reimport
When the MD5 checksum of the source asset changes, Pandemonium will perform an
automatic reimport of it, applying the preset configured for that specific
asset.
Files generated
-----------------
## Files generated
Importing will add an extra `<asset>.import` file, containing the import
configuration. Make sure to commit these to your version control system!
@ -83,8 +76,7 @@ to the version control system is optional. It can shorten
reimporting time when checking out on another computer, but it takes considerably
more space and transfer time. Pick your poison!
Changing import resource type
-----------------------------
## Changing import resource type
Some source assets can be imported as different types of resources.
For this, select the relevant type of resource desired and
@ -93,8 +85,7 @@ press "Reimport":
![](img/asset_workflow2.png)
Changing default import parameters
-----------------------------------
## Changing default import parameters
Different types of games might require different defaults.
Changing the defaults per project can be achieved by using the
@ -103,8 +94,7 @@ the default setting can be saved and cleared too:
![](img/asset_workflow3.png)
Simplicity is key!
------------------
## Simplicity is key!
This is a very simple workflow which should take very little time to get used to. It also enforces a more
correct way to deal with resources.

90
03_usage/21_assets_pipeline/02_importing_images.md
View File

@ -1,10 +1,8 @@
Importing images
================
# Importing images
Supported image formats
-----------------------
## Supported image formats
Pandemonium can import the following image formats:
@ -37,8 +35,7 @@ Note:
If you've compiled the Pandemonium editor from source with specific modules disabled,
some formats may not be available.
Importing textures
------------------
## Importing textures
The default action in Pandemonium is to import images as textures. Textures are stored
in video memory and can't be accessed directly. This is what makes drawing them
@ -48,20 +45,17 @@ Import options are vast:
![](img/image_import1.png)
Detect 3D
~~~~~~~~~
### Detect 3D
This option makes Pandemonium be aware of when a texture (which is imported for 2D as default) is used in 3D. If this happens, setting are changed so the texture flags
are friendlier to 3D (mipmaps, filter and repeat become enabled and compression is changed to VRAM). Texture is also reimported automatically.
Compression
-----------
## Compression
Images are one of the largest assets in a game. To handle them efficiently, they need to be compressed.
Pandemonium offers several compression methods, depending on the use case.
Compress Mode
~~~~~~~~~~~~~
### Compress Mode
- **VRAM Compression:** This is the most common compression mode for 3D assets.
Size on disk is reduced and video memory usage is also decreased considerably
@ -79,40 +73,26 @@ Compress Mode
raw float images).
In this table, each of the four options are described together with their
advantages and disadvantages (|good| = best, |bad| = worst):
advantages and disadvantages (![](img/good.png) = best, ![](img/bad.png) = worst):
+----------------+------------------------+-------------------------------+-------------------------+------------------------------------------------------+
| | Uncompressed | Compress Lossless | Compress Lossy | Compress VRAM |
+================+========================+===============================+=========================+======================================================+
|----------------|------------------------|-------------------------------|-------------------------|------------------------------------------------------|
| Description | Stored as raw pixels | Stored as Lossless WebP / PNG | Stored as Lossy WebP | Stored as S3TC/BC or PVRTC/ETC depending on platform |
+----------------+------------------------+-------------------------------+-------------------------+------------------------------------------------------+
| Size on Disk | |bad| Large | |regular| Small | |good| Very Small | |regular| Small |
+----------------+------------------------+-------------------------------+-------------------------+------------------------------------------------------+
| Memory Usage | |bad| Large | |bad| Large | |bad| Large | |good| Small |
+----------------+------------------------+-------------------------------+-------------------------+------------------------------------------------------+
| Performance | |regular| Normal | |regular| Normal | |regular| Normal | |good| Fast |
+----------------+------------------------+-------------------------------+-------------------------+------------------------------------------------------+
| Quality Loss | |good| None | |good| None | |regular| Slight | |bad| Moderate |
+----------------+------------------------+-------------------------------+-------------------------+------------------------------------------------------+
| Load Time | |regular| Normal | |bad| Slow | |bad| Slow | |good| Fast |
+----------------+------------------------+-------------------------------+-------------------------+------------------------------------------------------+
| Size on Disk | ![](img/bad.png) Large | ![](img/regular.png) Small | ![](img/good.png) Very Small | ![](img/regular.png) Small |
| Memory Usage | ![](img/bad.png) Large | ![](img/bad.png) Large | ![](img/bad.png) Large | ![](img/good.png) Small |
| Performance | ![](img/regular.png) Normal | ![](img/regular.png) Normal | ![](img/regular.png) Normal | ![](img/good.png) Fast |
| Quality Loss | ![](img/good.png) None | ![](img/good.png) None | ![](img/regular.png) Slight | ![](img/bad.png) Moderate |
| Load Time | ![](img/regular.png) Normal | ![](img/bad.png) Slow | ![](img/bad.png) Slow | ![](img/good.png) Fast |
.. |bad| image:: img/bad.png)
.. |good| image:: img/good.png)
.. |regular| image:: img/regular.png)
HDR Mode
~~~~~~~~
### HDR Mode
Pandemonium supports high dynamic range textures (as .HDR or .EXR). These are mostly useful as high dynamic range equirectangular panorama skies (the internet
has plenty if you search for them), which replace Cubemaps in Pandemonium 2.x. Modern PCs support the BC6H VRAM format, but there are still plenty that do not.
If you want Pandemonium to ensure full compatibility in terms of the kind of textures, enable the "Force RGBE" option.
Normal Map
~~~~~~~~~~
### Normal Map
When using a texture as normal map, only the red and green channels are required. Given regular texture compression algorithms produce artifacts that don't
look that nice in normal maps, the RGTC compression format is the best fit for this data. Forcing this option to "Enabled" will make Pandemonium import the
@ -123,7 +103,6 @@ Note that RGTC compression affects the resulting normal map image. You will have
Note:
Pandemonium requires the normal map to use the X+, Y+ and Z+ coordinates, this is
known as OpenGL style. If you've imported a material made to be used with
another engine it may be DirectX style, in which case the normal map needs to
@ -133,25 +112,21 @@ Note:
popular engines) can be found
`here ( http://wiki.polycount.com/wiki/Normal_Map_Technical_Details )`.
Flags
-----
## Flags
There are plenty of settings that can be toggled when importing an image as a texture, depending on the use case.
Repeat
~~~~~~
### Repeat
This setting is most commonly used in 3D, and is therefore generally disabled in 2D. It sets UV coordinates going beyond the 0,0 - 1,1 range to "loop".
Repeating can optionally be set to mirrored mode.
Filter
~~~~~~
### Filter
When pixels become larger than the screen pixels, this option enables linear interpolation for them. The result is a smoother (less blocky) texture. This setting can be commonly used in 2D and 3D, but it's usually disabled when making pixel perfect games.
Mipmaps
~~~~~~~
### Mipmaps
When pixels become smaller than the screen, mipmaps kick in. This helps reduce the grainy effect when shrinking the textures. Keep in mind that, in older hardware
(GLES2, mainly mobile), there are some requirements to use mipmaps:
@ -163,13 +138,11 @@ Keep in mind the above when making phone games and applications, want to aim for
When doing 3D, mipmap should be turned on, as this also improves performance (smaller versions of the texture are used for objects further away).
Anisotropic
~~~~~~~~~~~
### Anisotropic
When textures are near parallel to the view (like floors), this option makes them have more detail by reducing blurriness.
sRGB
~~~~
### sRGB
Pandemonium uses Linear colorspace when rendering 3D. Textures mapped to albedo or detail channels need to have this option turned on in order for colors to look correct.
When set to **Detect** mode, the texture will be marked as sRGB when used in albedo channels.
@ -185,13 +158,11 @@ Warning:
sRGB on one of the copies only. Use the copy with sRGB enabled in 3D, and
the copy with sRGB disabled in 2D.
Process
-------
## Process
Some special processes can be applied to images when imported as textures.
Fix Alpha Border
~~~~~~~~~~~~~~~~
### Fix Alpha Border
This puts pixels of the same surrounding color in transition from transparency to non transparency. It helps mitigate the outline effect when exporting images
from Photoshop and the like.
@ -200,26 +171,21 @@ from Photoshop and the like.
It's a good idea to leave it on by default, unless specific values are needed.
Premultiplied Alpha
~~~~~~~~~~~~~~~~~~~
### Premultiplied Alpha
An alternative to fix darkened borders is to use premultiplied alpha. By enabling this option, the texture will be converted to this format.
Keep in mind that a material will need to be created that uses the PREMULT ALPHA blend mode on canvas items that need it.
HDR as sRGB
~~~~~~~~~~~
### HDR as sRGB
A few HDR files are broken and contain sRGB color data. It is advised not to use them, but, in the worst-case scenario, toggling this option on will make them look right.
Invert Color
~~~~~~~~~~~~
### Invert Color
Reverses the image's color. This is useful, for example, to convert a height map generated by external programs to depth map to use with `doc_spatial_material`.
Svg
---
## Svg
Scale
~~~~~
### Scale
This option only applies to SVG files. It controls the scale of the SVG image. The default scale (1.0) will make the imported SVG match its original design scale.

26
03_usage/21_assets_pipeline/03_importing_audio_samples.md
View File

@ -1,10 +1,8 @@
Importing audio samples
=======================
# Importing audio samples
Supported files
---------------
## Supported files
Pandemonium provides three options to import your audio data: WAV, Ogg Vorbis
and MP3.
@ -27,27 +25,21 @@ Each has different advantages.
Here is a comparative chart.
+-----------------------------+-------------------+
| Format | 1 second of audio |
+=============================+===================+
|-----------------------------|-------------------|
| WAV 24-bit, 96 kHz, stereo | 576 KB |
+-----------------------------+-------------------+
| WAV 16-bit, 44 kHz, mono | 88 KB |
+-----------------------------+-------------------+
| WAV 16-bit, IMA-ADPCM, mono | 22 KB |
+-----------------------------+-------------------+
| MP3 192 Kb/s, stereo | 24 KB |
+-----------------------------+-------------------+
| Ogg Vorbis 128 Kb/s, stereo | 16 KB |
+-----------------------------+-------------------+
| Ogg Vorbis 96 Kb/s, stereo | 12 KB |
+-----------------------------+-------------------+
Consider using WAV for short and repetitive sound effects, and Ogg Vorbis
for music, speech, and long sound effects.
Best practices
--------------
## Best practices
Pandemonium has an `extensive bus system ( doc_audio_buses )` with built-in effects.
This saves SFX artists the need to add reverb to the sound effects,
@ -58,8 +50,7 @@ with baked reverb!
As you can see above, sound effects become huge with reverb added.
Trimming
~~~~~~~~
### Trimming
One issue that happens often is that the waveform is exported with long
silences at the beginning and at the end. These are inserted by
@ -69,8 +60,7 @@ add latency to the moment they are played back.
Importing as WAV with the **Trimming** option enabled solves
this.
Looping
~~~~~~~
### Looping
Pandemonium supports looping in the samples (tools such as Sound Forge or
Audition can add loop points to WAV files). This is useful for sound

30
03_usage/21_assets_pipeline/04_importing_translations.md
View File

@ -1,10 +1,7 @@
# Importing translations
Importing translations
======================
Games and internationalization
------------------------------
## Games and internationalization
The world is full of different languages and cultures, so nowadays games
are released in several languages. To handle this, internationalized text
@ -34,8 +31,7 @@ Note:
loading translations written in the gettext `.po` format. See
`doc_localization_using_gettext` for details.
Translation format
------------------
## Translation format
To complete the picture and allow efficient support for translations,
Pandemonium has a special importer that can read CSV files. Most spreadsheet
@ -55,15 +51,13 @@ Warning:
CSV files must be formatted as follows:
+--------+----------+----------+----------+
| keys | <lang1> | <lang2> | <langN> |
+========+==========+==========+==========+
|--------|----------|----------|----------|
| KEY1 | string | string | string |
+--------+----------+----------+----------+
| KEY2 | string | string | string |
+--------+----------+----------+----------+
| KEYN | string | string | string |
+--------+----------+----------+----------+
The "lang" tags must represent a language, which must be one of the `valid
locales ( doc_locales )` supported by the engine. The "KEY" tags must be
@ -74,17 +68,14 @@ runtime by the matching translated string. Note that the case is important,
The top-left cell is ignored and can be left empty or having any content.
Here's an example:
+-------+-----------------------+------------------------+------------------------------+
| keys | en | es | ja |
+=======+=======================+========================+==============================+
|-------|-----------------------|------------------------|------------------------------|
| GREET | Hello, friend! | Hola, amigo! | こんにちは |
+-------+-----------------------+------------------------+------------------------------+
| ASK | How are you? | Cómo está? | 元気ですか |
+-------+-----------------------+------------------------+------------------------------+
| BYE | Goodbye | Adiós | さようなら |
+-------+-----------------------+------------------------+------------------------------+
| QUOTE | "Hello" said the man. | "Hola" dijo el hombre. | 「こんにちは」男は言いました |
+-------+-----------------------+------------------------+------------------------------+
The same example is shown below as a comma-separated plain text file,
which should be the result of editing the above in a spreadsheet.
@ -104,8 +95,7 @@ comma in the import options.
QUOTE,"""Hello"" said the man.","""Hola"" dijo el hombre.",「こんにちは」男は言いました
```
CSV importer
------------
## CSV importer
Pandemonium will treat CSV files as translations by default. It will import them
and generate one or more compressed translation resource files next to it.

135
03_usage/21_assets_pipeline/05_importing_scenes.md
View File

@ -1,10 +1,8 @@
Importing 3D scenes
===================
# Importing 3D scenes
Pandemonium scene importer
--------------------
## Pandemonium scene importer
When dealing with 3D assets, Pandemonium has a flexible and configurable importer.
@ -25,8 +23,7 @@ Just copy the scene file together with the texture to the project repository, an
It is important that the mesh is not deformed by bones when exporting. Make sure that the skeleton is reset to its T-pose
or default rest pose before exporting with your favorite 3D editor.
Exporting DAE files from Maya and 3DS Max
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
### Exporting DAE files from Maya and 3DS Max
Autodesk added built-in COLLADA support to Maya and 3DS Max, but it's
broken by default and should not be used. The best way to export this format
@ -35,8 +32,7 @@ is by using the
plugins. They work well, although they are not always up-to date
with the latest version of the software.
Exporting glTF 2.0 files from Blender
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
### Exporting glTF 2.0 files from Blender
There are three ways to export glTF files from Blender. As a glTF binary (`.glb` file), glTF embedded (`.gltf` file),
and with textures (`gltf` + `.bin` + textures).
@ -54,12 +50,10 @@ either of those glTF binary files are fine.
Warning:
Blend shape animations cannot be imported - they require manual animation within Pandemonium.
Note:
Blender versions older than 3.2 do not export emissive textures with the
glTF file. If your model uses one and you're using an older version of
Blender, it must be brought in separately.
@ -71,8 +65,7 @@ Note:
being culled by other faces. To resolve this, enable **Backface Culling** in
Blender's Materials tab, then export the scene to glTF again.
Exporting DAE files from Blender
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
### Exporting DAE files from Blender
Blender has built-in COLLADA support, but it does not work properly for the needs of game engines
and should not be used as is.
@ -81,8 +74,7 @@ Pandemonium provides a `Blender plugin ( https://github.com/pandemoniumengine/co
that will correctly export COLLADA scenes for use in Pandemonium. It does not work in Blender 2.8 or
newer, but there are plans to update it in the future.
Exporting ESCN files from Blender
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
### Exporting ESCN files from Blender
The most powerful one, called `pandemonium-blender-exporter
( https://github.com/Relintai/pandemonium_engine-blender-exporter )`.
@ -90,11 +82,10 @@ It uses a .escn file, which is kind of another name for a .tscn file (Pandemoniu
it keeps as much information as possible from a Blender scene. However, it is considered
experimental.
The ESCN exporter has a detailed `document <escn_exporter/index.html )` describing
The ESCN exporter has a detailed `document ( escn_exporter/index.html )` describing
its functionality and usage.
Exporting textures separately
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
### Exporting textures separately
While textures can be exported with a model in certain file formats, such as glTF 2.0, you can also export them
separately. Pandemonium uses PBR (physically based rendering) for its materials, so if a texturing program can export PBR
@ -104,8 +95,7 @@ textures, they can work in Pandemonium. This includes the `Substance suite ( htt
Note:
For more information on Pandemonium's materials, see `doc_spatial_material`.
Exporting considerations
~~~~~~~~~~~~~~~~~~~~~~~~
### Exporting considerations
Since GPUs can only render triangles, meshes that contain quads or N-gons have
to be *triangulated* before they can be rendered. Pandemonium can triangulate meshes
@ -124,8 +114,7 @@ in the export dialog.
To avoid issues with 3D selection in the editor, it is recommended to apply the
object transform in the 3D DCC before exporting the scene.
Import workflows
----------------
## Import workflows
Pandemonium scene importer allows different workflows regarding how data is imported. Depending on many options, it is possible to
import a scene with:
@ -140,33 +129,27 @@ import a scene with:
As different developers have different needs, this import process is highly customizable.
Import options
--------------
## Import options
The importer has several options, which will be discussed below:
![](img/scene_import2.png)
Nodes
~~~~~
### Nodes
Root Type
^^^^^^^^^
#### Root Type
By default, the type of the root node in imported scenes is "Spatial", but this can be modified.
Root Name
^^^^^^^^^
#### Root Name
Allows setting a specific name to the generated root node.
Root Scale
^^^^^^^^^^
#### Root Scale
The scale of the root node.
Custom Script
^^^^^^^^^^^^^
#### Custom Script
A special script to process the whole scene after import can be provided.
This is great for post processing, changing materials, doing funny stuff
@ -188,8 +171,7 @@ The `post_import` function takes the imported scene as argument (the
parameter is actually the root node of the scene). The scene that
will finally be used must be returned. It can be a different one.
Storage
^^^^^^^
#### Storage
By default, Pandemonium imports a single scene. This option allows specifying
that nodes below the root will each be a separate scene and instanced
@ -197,18 +179,14 @@ into the imported one.
Of course, instancing such imported scenes in other places manually works, too.
### Materials
Materials
~~~~~~~~~
Location
^^^^^^^^
#### Location
Pandemonium supports materials in meshes or nodes. By default, materials will be put
on each node.
Storage
^^^^^^^
#### Storage
Materials can be stored within the scene or in external files. By default,
they are stored in external files so editing them is possible. This is because
@ -228,18 +206,15 @@ Note:
dock, going to the Import dock then setting **Material > Storage** to
**Built-In** instead of **Files**.
Keep On Reimport
^^^^^^^^^^^^^^^^
#### Keep On Reimport
Once materials are edited to use Pandemonium features, the importer will keep the
edited ones and ignore the ones coming from the source scene. This option
is only present if materials are saved as files.
Meshes
~~~~~~
### Meshes
Compress
^^^^^^^^
#### Compress
Makes meshes use less precise numbers for multiple aspects of the mesh in order
to save space.
@ -265,16 +240,14 @@ may be needed. For instance, if a mesh is very big or there are multiple meshes
being imported that cover a large area, compressing the import of this mesh(es)
may lead to gaps in geometry or vertices not being exactly where they should be.
Ensure Tangents
^^^^^^^^^^^^^^^
#### Ensure Tangents
If textures with normal mapping are to be used, meshes need to have tangent arrays.
This option ensures that these are generated if not present in the source scene.
Pandemonium uses `Mikktspace ( http://www.mikktspace.com/ )` for this,
but it's always better to have them generated in the exporter.
Storage
^^^^^^^
#### Storage
Meshes can be stored in separate files (resources) instead of built-in. This does
not have much practical use unless one wants to build objects with them directly.
@ -282,8 +255,7 @@ not have much practical use unless one wants to build objects with them directly
This option is provided to help those who prefer working directly with meshes
instead of scenes.
Light Baking
^^^^^^^^^^^^
#### Light Baking
Whether or not the mesh is used in baked lightmaps.
@ -294,14 +266,12 @@ Whether or not the mesh is used in baked lightmaps.
Note:
For more information on light baking see `doc_baked_lightmaps`.
External Files
~~~~~~~~~~~~~~
### External Files
Generated meshes and materials can be optionally stored in a subdirectory with the
name of the scene.
Animation options
-----------------
## Animation options
Pandemonium provides many options regarding how animation data is dealt with. Some exporters
(such as Blender) can generate many animations in a single file. Others, such as
@ -312,21 +282,19 @@ each animation in a separate file.
Import of animations is enabled by default.
.. attention::
Attention:
To modify animations from an imported 3D scene, you need to change the animation
storage option from **Built-In** to **Files** in the Import dock. Otherwise,
changes made to animations from Pandemonium will be lost when the project is run.
FPS
~~~
### FPS
Most 3D export formats store animation timeline in seconds instead of frames. To ensure
animations are imported as faithfully as possible, please specify the frames per second
used to edit them. Failing to do this may result in shaky animations.
Filter Script
~~~~~~~~~~~~~
### Filter Script
It is possible to specify a filter script in a special syntax to decide which tracks from which
animations should be kept.
@ -378,31 +346,27 @@ as `"Skeleton:Head"` or `"Skeleton:Arm_Left_Control"` would be retained.
Any track filter lines that do not begin with a `+` or `-` are ignored.
Storage
~~~~~~~
### Storage
By default, animations are saved as built-in. It is possible to save them to a file instead. This
allows adding custom tracks to the animations and keeping them after a reimport.
Optimizer
~~~~~~~~~
### Optimizer
When animations are imported, an optimizer is run, which reduces the size of the animation considerably.
In general, this should always be turned on unless you suspect that an animation might be broken due to it being enabled.
Clips
~~~~~
### Clips
It is possible to specify multiple animations from a single timeline as clips. For this to work, the model
must have only one animation that is named `default`. To create clips, change the clip amount to something
greater than zero. You can then name a clip, specify which frames it starts and stops on, and choose whether
the animation loops or not.
.. If this PR (https://github.com/Relintai/pandemonium_engine/pull/36709) is merged for Pandemonium 4.0 this section must
If this PR (https://github.com/Relintai/pandemonium_engine/pull/36709) is merged for Pandemonium 4.0 this section must
be updated to reflect that for the 4.0 documentation.
Scene inheritance
-----------------
## Scene inheritance
In many cases, it may be desired to make modifications to the imported scene. By default, this is not possible because
if the source asset changes (source `.dae`, `.gltf`, `.obj` file re-exported from 3D modelling app), Pandemonium will re-import the whole scene.
@ -421,8 +385,7 @@ Other than that, everything is allowed!
Import hints
------------
## Import hints
Many times, when editing a scene, there are common tasks that need to be done after exporting:
@ -436,17 +399,14 @@ will detect suffixes in object names and will perform actions automatically.
Note:
All the suffixes described below are *case-sensitive*.
Remove nodes (-noimp)
~~~~~~~~~~~~~~~~~~~~~
### Remove nodes (-noimp)
Objects that have the `-noimp` suffix will be removed at import-time no matter
what their type is. They will not appear in the imported scene.
Create collisions (-col, -convcol, -colonly, -convcolonly)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
### Create collisions (-col, -convcol, -colonly, -convcolonly)
The option `-col` will work only for Mesh objects. If it is detected, a child
static collision node will be added, using the same geometry as the mesh. This
@ -491,42 +451,35 @@ reliability.
Note:
For better visibility in Blender's editor, you can set the "X-Ray" option
on collision empties and set some distinct color for them in Blender's
**User Preferences > Themes > 3D View > Empty**.
See also:
See `doc_collision_shapes_3d` for a comprehensive overview of collision
shapes.
Create navigation (-navmesh)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
### Create navigation (-navmesh)
A mesh node with the `-navmesh` suffix will be converted to a navigation mesh.
The original Mesh object will be removed at import-time.
Create a VehicleBody (-vehicle)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
### Create a VehicleBody (-vehicle)
A mesh node with the `-vehicle` suffix will be imported as a child to a
`VehicleBody` node.
Create a VehicleWheel (-wheel)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
### Create a VehicleWheel (-wheel)
A mesh node with the `-wheel` suffix will be imported as a child to a
`VehicleWheel` node.
Rigid Body (-rigid)
~~~~~~~~~~~~~~~~~~~
### Rigid Body (-rigid)
A mesh node with the `-rigid` suffix will be imported as a `RigidBody`.
Animation loop (-loop, -cycle)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
### Animation loop (-loop, -cycle)
Animation clips in the COLLADA document that start or end with the token `loop` or `cycle`
will be imported as a Pandemonium Animation with the loop flag set.

9
03_usage/21_assets_pipeline/06_exporting_3d_scenes.md
View File

@ -1,10 +1,8 @@
Exporting 3D scenes
===================
# Exporting 3D scenes
Overview
--------
## Overview
In Pandemonium it is possible to export 3D scenes as a glTF 2.0 file. You can
export as a glTF binary (`.glb` file) or glTF embedded with textures
@ -21,8 +19,7 @@ To export a scene in the editor go to **Project > Tools > Export GLTF...**
![](img/gltf_pandemonium_export.png)
Limitations
-----------
## Limitations
There are several limitations with glTF export.

27
03_usage/21_assets_pipeline/escn_exporter/01_introduction.md
View File

@ -1,5 +1,5 @@
Blender ESCN exporter
=====================
# Blender ESCN exporter
Note:
This chapter relates to the Blender plugin called "Pandemonium Blender Exporter",
@ -9,36 +9,19 @@ This plugin can be used to export Blender scenes in a Pandemonium-specific scene
called ESCN, which is similar to TSCN (text format) but will be imported as binary
SCN for performance.
Details on exporting
--------------------
.. toctree::
:maxdepth: 1
:name: toc-learn-workflow-assets-escn_exporter
material
physics
lights
mesh
skeleton
animation
Disabling specific objects
--------------------------
## Disabling specific objects
Sometimes you don't want some objects exported (e.g. high-res models used for
baking). An object will not be exported if it is not rendered in the scene.
This can be set in the outliner:
![](img/hide.jpg
![](img/hide.jpg)
Objects hidden in the viewport will be exported, but will be hidden in the
Pandemonium scene.
Build pipeline integration
--------------------------
## Build pipeline integration
If you have hundreds of model files, you don't want your artists to waste time
manually exporting their blend files. To combat this, the exporter provides a

19
03_usage/21_assets_pipeline/escn_exporter/02_material.md
View File

@ -1,8 +1,7 @@
Materials
=========
Using existing Pandemonium materials
------------------------------
# Materials
## Using existing Pandemonium materials
One way in which the exporter can handle materials is to attempt to match
the Blender material with an existing Pandemonium material. This has the advantage of
@ -20,7 +19,7 @@ exporter will fall back to exporting the material from Blender.
Where the exporter searches for the `.tres` file is determined by the "Material
Search Paths" option:
![](img/material_search.jpg
![](img/material_search.jpg)
This can take the value of:
- Project Directory - Attempts to find the `project.Pandemonium` and recursively
@ -33,8 +32,7 @@ This can take the value of:
- None - Do not search for materials. Export them from the Blender file.
Export of Cycles/EEVEE materials
--------------------------------
## Export of Cycles/EEVEE materials
The exporter has a primitive support for converting Cycles/EEVEE material node tree
to Pandemonium Shader Material. Note that some of the Shader Node are not supported yet due to
@ -56,15 +54,14 @@ is using Blender Internal Engine, only the diffuse color and a few flags (e.g. u
exported and form a Spatial Material.
Generate external materials
---------------------------
## Generate external materials
The default configuration of material exporting would keep all the materials internal to
the `escn` file. There is an option which could enable generating external `.material`
file when the `escn` file opens in Pandemonium.
![](img/external_mat_option.jpg
![](img/external_mat_option.jpg)
`.material` file can be assigned to any material slot to be a external resource.
![](img/gd_dot_material.jpg
![](img/gd_dot_material.jpg)

20
03_usage/21_assets_pipeline/escn_exporter/03_physics.md
View File

@ -1,33 +1,32 @@
Physics properties
==================
# Physics properties
Exporting physics properties is done by enabling "Rigid Body" in Blender's
physics tab:
![](img/enable_physics.png)
.. important::
Important:
By default, a single Blender object with rigid body enabled will export as
three nodes: a PhysicsBody, a CollisionShape, and a MeshInstance.
Body type
---------
## Body type
Blender only has the concept of "Active" and "Passive" rigid bodies. These
turn into Static and RigidBody nodes. To create a kinematic body, enable the
"animated" checkbox on an "Active" body:
![](img/body_type.jpg
![](img/body_type.jpg)
Collision shapes
----------------
## Collision shapes
Many of the parameters for collision shapes are missing from Blender, and many
of the collision shapes are also not present. However, almost all of the
options in Blender's rigid body collision and rigid body dynamics interfaces
are supported:
![](img/collision_shapes.jpg
![](img/collision_shapes.jpg)
There are the following caveats:
- Not all of the collision shapes are supported. Only `Mesh`, `Convex
@ -43,8 +42,7 @@ There are the following caveats:
rigid body enabled. The physics properties are taken from the parent-most
rigid body, and the rest are used as collision shapes.
Collision geometry only
-----------------------
## Collision geometry only
Frequently you want different geometry for your collision meshes and your
graphical meshes, but by default, the exporter will export a mesh along with the

7
03_usage/21_assets_pipeline/escn_exporter/04_lights.md
View File

@ -1,5 +1,6 @@
Lights
======
# Lights
Warning:
By default, lamps in Blender have shadows enabled. This can cause
@ -13,7 +14,7 @@ Warning:
Sun, point and spot lamps are all exported from Blender along with many of their
properties:
![](img/light_properties.jpg
![](img/light_properties.jpg)
There are some things to note:

12
03_usage/21_assets_pipeline/escn_exporter/05_mesh.md
View File

@ -1,14 +1,14 @@
Mesh
====
Modifiers
---------
# Mesh
## Modifiers
There is an exporting option :code:`Apply Modifiers` to
control whether mesh modifiers are applied to the exported mesh.
Shape Key
---------
## Shape Key
Exporting mesh shape key is supported, however exporting each shape key
is almost like exporting the mesh again, so don't be surprised
it takes a relatively long time.

18
03_usage/21_assets_pipeline/escn_exporter/06_skeleton.md
View File

@ -1,10 +1,10 @@
Skeleton
# Skeleton
========
![](img/armature.jpg
![](img/armature.jpg)
Rest Bone
---------
## Rest Bone
Armature object in Blender is exported as a Skeleton node along with
rest position (transform in Pandemonium) of bones.
@ -19,23 +19,21 @@ Warning:
It is important that the mesh is not deformed by bones when exporting in Blender. Make sure
that the skeleton is reset to its T-pose or default rest pose.
Bone Weights
------------
## Bone Weights
Blender put rigged mesh vertices which has no bone weights at its original
position, but these vertices would be placed at (0, 0, 0) in Pandemonium, making the mesh
deformed. Therefore, the exporter would raise an error for any vertex with no bone weights
detected in a rigged mesh.
Non-Deform Bone
---------------
## Non-Deform Bone
Note that the non-deform bone can be configured as not exported
by enabling the :code:`Exclude Control Bones`; the deform bone
checkbox is shown in the picture.
Bone Attachment
---------------
## Bone Attachment
A bone can be the parent of an object in Blender; this relation is exported
as a BoneAttachment node in the Pandemonium scene.

31
03_usage/21_assets_pipeline/escn_exporter/07_animation.md
View File

@ -1,5 +1,6 @@
Animation
=========
# Animation
Animation supported:
- transform animation of all types of objects
- transform animation of pose bones
@ -7,8 +8,8 @@ Animation supported:
- light animation
- camera animation
Multiple Actions For Single Object
----------------------------------
## Multiple Actions For Single Object
In most games, one object would have several animations to switch between.
This add-on has support for exporting multiple actions all at once into
a single AnimationPlayer and makes it easy to switch actions.
@ -22,13 +23,13 @@ New created action is always an active action bound to object. There are
several ways to place an active action into NLA track,
one is of course doing it in `NLA Editor`
![](img/nla_editor.jpg
![](img/nla_pushdown.jpg
![](img/nla_editor.jpg)
![](img/nla_pushdown.jpg)
Or it can be done stashing the action in `Dope Sheet`
![](img/dope_sheet.jpg
![](img/stash_action.jpg
![](img/dope_sheet.jpg)
![](img/stash_action.jpg)
**2. Check mute status of NLA tracks**
@ -36,30 +37,30 @@ An NLA track can be `mute` or `unmute`, the exporter will export all
the `mute` NLA track as a separate action, while blends all the `unmute`
NLA tracks into every action (including the action action) being exported.
![](img/nla_strip.jpg
![](img/nla_strip.jpg)
**3. Export the scene**
Make sure the `Export Stashed Actions` option has been turned on.
![](img/stash_action_option.jpg
![](img/stash_action_option.jpg)
Then all the stashed actions, as well as the active action, are exported
to an AnimationPlayer.
![](img/in_pandemonium.jpg
![](img/in_pandemonium.jpg)
Constraints
-----------
## Constraints
Sometimes complicated animation is built with object constraint; a usual
example is inverse kinematics. The add-on would automatically check if an
object has some constraint; if it does, all the constraints are baked into
actions and then exported along with the object.
Animation Mode
---------------------------
## Animation Mode
Pandemonium and Blender have different structure to store animation data.
In Pandemonium animation data is stored in an AnimationPlayer node, instead
of in each animated node. In order to fix this inconsistence and still

0
03_usage/21_assets_pipeline/escn_exporter/img/in_godot.jpg → 03_usage/21_assets_pipeline/escn_exporter/img/in_pandemonium.jpg
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 40 KiB

After

Width:  |  Height:  |  Size: 40 KiB

0
03_usage/21_assets_pipeline/img/gltf_godot_export.png → 03_usage/21_assets_pipeline/img/gltf_pandemonium_export.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 12 KiB

After

Width:  |  Height:  |  Size: 12 KiB

4
03_usage/22_best_practices/01_introduction_best_practices.md
View File

@ -1,7 +1,6 @@
Introduction
============
# Introduction
This series is a collection of best practices to help you work efficiently with
Pandemonium.
@ -23,7 +22,6 @@ Object-Oriented programming languages. It will help you make sense of the rest o
Note:
The best practices in Pandemonium rely on Object-Oriented design principles. We
use tools like the `single responsibility
( https://en.wikipedia.org/wiki/Single_responsibility_principle )` principle and

10
03_usage/22_best_practices/02_what_are_godot_classes.md
View File

@ -1,7 +1,5 @@
Applying object-oriented principles in Pandemonium
============================================
# Applying object-oriented principles in Pandemonium
The engine offers two main ways to create reusable objects: scripts and scenes. Neither of these
technically define classes under the hood.
@ -13,8 +11,7 @@ think of them as classes.
This guide briefly explains how scripts and scenes work in the engine's core to help you understand
how they work under the hood.
How scripts work in the engine
------------------------------
## How scripts work in the engine
The engine provides built-in classes like `Node`. You can extend those to create
derived types using a script.
@ -46,8 +43,7 @@ Note:
`extends` keyword from code. Since they extend `Reference` though, you cannot attach them to
a `Node`.
Scenes
------
## Scenes
The behavior of scenes has many similarities to classes, so it can make sense to think of a scene as
a class. Scenes are reusable, instantiable, and inheritable groups of nodes. Creating a scene is

9
03_usage/22_best_practices/03_scene_organization.md
View File

@ -1,14 +1,12 @@
Scene organization
==================
# Scene organization
This article covers topics related to the effective organization of
scene content. Which nodes should one use? Where should one place them?
How should they interact?
How to build relationships effectively
--------------------------------------
## How to build relationships effectively
When Pandemonium users begin crafting their own scenes, they often run into the
following problem:
@ -190,8 +188,7 @@ by *all* OOP principles. Examples include...
- `KISS ( https://en.wikipedia.org/wiki/KISS_principle )`
- `YAGNI ( https://en.wikipedia.org/wiki/You_aren%27t_gonna_need_it )`
Choosing a node tree structure
------------------------------
## Choosing a node tree structure
So, a developer starts work on a game only to stop at the vast possibilities
before them. They might know what they want to do, what systems they want to

15
03_usage/22_best_practices/04_scenes_versus_scripts.md
View File

@ -1,7 +1,6 @@
When to use scenes versus scripts
=================================
# When to use scenes versus scripts
We've already covered how scenes and scripts are different. Scripts
define an engine class extension with imperative code, scenes with
@ -12,8 +11,7 @@ Scenes can define how an extended class initializes, but not what its
behavior actually is. Scenes are often used in conjunction with a script so
that the scene acts as an extension of the scripts declarative code.
Anonymous types
---------------
## Anonymous types
It *is* possible to completely define a scenes' contents using a script alone.
This is, in essence, what the Pandemonium Editor does, only in the C++ constructor
@ -38,8 +36,7 @@ Also, scripts will operate a little slower than scenes due to the
speed differences between engine and script code. The larger and more complex
the node, the more reason there is to build it as a scene.
Named types
-----------
## Named types
In some cases, a user can register a script as a new type within the editor
itself. This displays it as a new type in the node or resource creation dialog
@ -125,8 +122,7 @@ this way.
On the downside, it also means having to use largely imperative programming.
Performance of Script vs PackedScene
------------------------------------
## Performance of Script vs PackedScene
One last aspect to consider when choosing scenes and scripts is execution speed.
@ -161,8 +157,7 @@ Scenes help to avoid this performance issue. `PackedScene
that use serialized data to create objects. The engine can process scenes in
batches on the back-end and provide much better performance than scripts.
Conclusion
----------
## Conclusion
In the end, the best approach is to consider the following:

12
03_usage/22_best_practices/05_autoloads_versus_internal_nodes.md
View File

@ -1,7 +1,6 @@
Autoloads versus regular nodes
==============================
# Autoloads versus regular nodes
Pandemonium offers a feature to automatically load nodes at the root of your project,
allowing you to access them globally, that can fulfill the role of a Singleton:
@ -11,8 +10,7 @@ change the scene from code with `SceneTree.change_scene`.
In this guide, you will learn when to use the Autoload feature, and techniques
you can use to avoid it.
The cutting audio issue
-----------------------
## The cutting audio issue
Other engines can encourage the use of creating manager classes, singletons that
organize a lot of functionality into a globally accessible object. Pandemonium offers
@ -61,8 +59,7 @@ needs within itself and all these problems go away:
3. Each scene allocates exactly the amount of resources it needs.
Managing shared functionality or data
-------------------------------------
## Managing shared functionality or data
Another reason to use an Autoload can be that you want to reuse the same method
or data across many scenes.
@ -78,8 +75,7 @@ When it comes to data, you can either:
2. Store the data in an object to which each node has access, for example using
the `owner` property to access the scene's root node.
When you should use an Autoload
-------------------------------
## When you should use an Autoload
Auto-loaded nodes can simplify your code in some cases:

4
03_usage/22_best_practices/06_node_alternatives.md
View File

@ -1,8 +1,6 @@
When and how to avoid using nodes for everything
================================================
# When and how to avoid using nodes for everything
Nodes are cheap to produce, but even they have their limits. A project may
have tens of thousands of nodes all doing things. The more complex their

11
03_usage/22_best_practices/07_pandemonium_interfaces.md
View File

@ -1,7 +1,6 @@
Pandemonium interfaces
================
# Pandemonium interfaces
Often one needs scripts that rely on other objects for features. There
are 2 parts to this process:
@ -12,8 +11,7 @@ are 2 parts to this process:
The rest of this tutorial outlines the various ways of doing all this.
Acquiring object references
---------------------------
## Acquiring object references
For all `Object`\s, the most basic way of referencing them
is to get a reference to an existing object from another acquired instance.
@ -131,10 +129,7 @@ gdscript GDScript
print(globals.my_getter())
```
Accessing data or logic from an object
--------------------------------------
## Accessing data or logic from an object
Pandemonium's scripting API is duck-typed. This means that if a script executes an
operation, Pandemonium doesn't validate that it supports the operation by **type**.

12
03_usage/22_best_practices/08_pandemonium_notifications.md
View File

@ -1,7 +1,6 @@
Pandemonium notifications
===================
# Pandemonium notifications
Every Object in Pandemonium implements a
`notification` method. Its purpose is to
@ -70,8 +69,7 @@ Note:
So, in which situation should one use each of these notifications or
virtual functions?
_process vs. _physics_process vs. \*_input
------------------------------------------
## _process vs. _physics_process vs. \*_input
Use `process` when one needs a framerate-dependent deltatime between
frames. If code that updates object data needs to update as often as
@ -124,8 +122,7 @@ gdscript GDScript
```
_init vs. initialization vs. export
-----------------------------------
## _init vs. initialization vs. export
If the script initializes its own node subtree, without a scene,
that code should execute here. Other property or SceneTree-independent
@ -170,8 +167,7 @@ following sequence:
As a result, instantiating a script versus a scene will affect both the
initialization *and* the number of times the engine calls the setter.
_ready vs. _enter_tree vs. NOTIFICATION_PARENTED
------------------------------------------------
## _ready vs. _enter_tree vs. NOTIFICATION_PARENTED
When instantiating a scene connected to the first executed scene, Pandemonium will
instantiate nodes down the tree (making `init` calls) and build the tree

18
03_usage/22_best_practices/09_data_preferences.md
View File

@ -1,7 +1,6 @@
Data preferences
================
# Data preferences
Ever wondered whether one should approach problem X with data structure
Y or Z? This article covers a variety of topics related to these dilemmas.
@ -37,8 +36,7 @@ Note:
algorithm / data structure for the job is part of what makes programmers'
skills valuable.
Array vs. Dictionary vs. Object
-------------------------------
## Array vs. Dictionary vs. Object
Pandemonium stores all variables in the scripting API in the
`Variant ( https://docs.pandemoniumengine.org/en/latest/development/cpp/variant_class.html )`
@ -46,7 +44,7 @@ class. Variants can store Variant-compatible data structures such as
`Array` as well as
`Object` s.
Pandemonium implements Array as a `Vector<Variant )`. The engine stores the Array
Pandemonium implements Array as a `Vector&lt;Variant&gt;`. The engine stores the Array
contents in a contiguous section of memory, i.e. they are in a row adjacent
to each other.
@ -57,7 +55,7 @@ Note:
type, meaning that its records can only contain a particular type (denoted
by angled brackets). So, for example, a
`PoolStringArray` would be something like
a `Vector<String )`.
a `Vector&lt;String&gt;`.
Contiguous memory stores imply the following operation performance:
@ -104,7 +102,7 @@ Contiguous memory stores imply the following operation performance:
though. Done by re-sorting the Array after every edit and writing an
ordered-aware search algorithm.
Pandemonium implements Dictionary as an `OrderedHashMap<Variant, Variant )`. The engine
Pandemonium implements Dictionary as an `OrderedHashMap&lt;Variant, Variant&gt;`. The engine
stores a small array (initialized to 2^3 or 8 records) of key-value pairs. When
one attempts to access a value, they provide it a key. It then *hashes* the
key, i.e. converts it into a number. The "hash" is used to calculate the index
@ -253,8 +251,7 @@ gdscript GDScript
From here, one can then create their own structures with specific features,
limited only by their imagination.
Enumerations: int vs. string
----------------------------
## Enumerations: int vs. string
Most languages offer an enumeration type option. GDScript is no different, but
unlike most other languages, it allows one to use either integers or strings for
@ -280,8 +277,7 @@ to group them together as related concepts, then it makes sense to use them as
strings. That way, a separate data structure to execute on the printing is
unnecessary.
AnimatedTexture vs. AnimatedSprite vs. AnimationPlayer vs. AnimationTree
------------------------------------------------------------------------
## AnimatedTexture vs. AnimatedSprite vs. AnimationPlayer vs. AnimationTree
Under what circumstances should one use each of Pandemonium's animation classes?
The answer may not be immediately clear to new Pandemonium users.

9
03_usage/22_best_practices/10_logic_preferences.md
View File

@ -1,13 +1,11 @@
Logic preferences
=================
# Logic preferences
Ever wondered whether one should approach problem X with strategy Y or Z?
This article covers a variety of topics related to these dilemmas.
Loading vs. preloading
----------------------
## Loading vs. preloading
In GDScript, there exists the global
`preload` method. It loads resources as
@ -98,8 +96,7 @@ consider:
`Reference`-extending type, will cause the
resources to delete themselves from memory).
Large levels: static vs. dynamic
--------------------------------
## Large levels: static vs. dynamic
If one is creating a large level, which circumstances are most appropriate?
Should they create the level as one static space? Or should they load the

31
03_usage/22_best_practices/11_project_organization.md
View File

@ -1,18 +1,15 @@
Project organization
====================
# Project organization
Introduction
------------
## Introduction
Since Pandemonium has no restrictions on project structure or filesystem usage,
organizing files when learning the engine can seem challenging. This
tutorial suggests a workflow which should be a good starting point.
We will also cover using version control with Pandemonium.
Organization
------------
## Organization
Pandemonium is scene-based in nature, and uses the filesystem as-is,
without metadata or an asset database.
@ -33,19 +30,18 @@ They can then use a separate folder to store built levels that use them.
/docs/.gdignore # See "Ignoring specific folders" below
/docs/learning.html
/models/town/house/house.dae
/models/town/house/window.png)
/models/town/house/door.png)
/models/town/house/window.png
/models/town/house/door.png
/characters/player/cubio.dae
/characters/player/cubio.png)
/characters/player/cubio.png
/characters/enemies/goblin/goblin.dae
/characters/enemies/goblin/goblin.png)
/characters/enemies/goblin/goblin.png
/characters/npcs/suzanne/suzanne.dae
/characters/npcs/suzanne/suzanne.png)
/characters/npcs/suzanne/suzanne.png
/levels/riverdale/riverdale.scn
```
Style guide
-----------
## Style guide
For consistency across projects, we recommend following these guidelines:
@ -61,8 +57,7 @@ For consistency across projects, we recommend following these guidelines:
third-party game assets for a character, it makes more sense to include them
within the same folder as the character scenes and scripts.
Importing
---------
## Importing
Pandemonium versions prior to 3.0 did the import process from files outside
the project. While this can be useful in large projects, it
@ -71,8 +66,7 @@ resulted in an organization hassle for most developers.
Because of this, assets are now transparently imported from within the project
folder.
Ignoring specific folders
~~~~~~~~~~~~~~~~~~~~~~~~~
### Ignoring specific folders
To prevent Pandemonium from importing files contained in a specific folder, create
an empty file called `.gdignore` in the folder (the leading `.` is required).
@ -80,7 +74,6 @@ This can be useful to speed up the initial project importing.
Note:
To create a file whose name starts with a dot on Windows, you can use a
text editor such as Notepad++ or use the following command in a
command prompt: `type nul > .gdignore`
@ -94,7 +87,7 @@ should be empty. It does not support patterns like `.gitignore` files do.
Case sensitivity
## Case sensitivity
----------------
Windows and recent macOS versions use case-insensitive filesystems by default,

15
03_usage/22_best_practices/12_version_control_systems.md
View File

@ -1,10 +1,8 @@
Version Control Systems
=======================
# Version Control Systems
Introduction
------------
## Introduction
Pandemonium aims to be VCS friendly and generate mostly readable and mergeable files.
Pandemonium also supports the use of version control systems in the editor itself.
@ -13,8 +11,7 @@ VCS can be setup or shut down in the editor under **Project > Version Control**.
![](img/version_control_menu.png)
Official Git plugin
-------------------
## Official Git plugin
Using Git from inside the editor is supported with an official plugin.
You can find the latest releases
@ -22,8 +19,7 @@ You can find the latest releases
plugin can be found
`here ( https://github.com/Relintai/pandemonium_engine-git-plugin/wiki )`.
Files to exclude from VCS
-------------------------
## Files to exclude from VCS
There are some folders Pandemonium creates you should have your VCS ignore:
@ -35,8 +31,7 @@ There are some folders Pandemonium creates you should have your VCS ignore:
- `.mono/`: This folder stores automatically-generated Mono files. It only exists
in projects that use the Mono version of Pandemonium.
Working with Git on Windows
---------------------------
## Working with Git on Windows
Most Git for Windows clients are configured with the `core.autocrlf` set to `true`.
This can lead to files unnecessarily being marked as modified by Git due to their line endings being converted automatically.

4
03_usage/22_best_practices/13_list_of_tricks.md
View File

@ -1,8 +1,8 @@
# Things that are not documented nor indicated anywhere
From https://github.com/godotengine/godot-docs/issues/4377
Things that are not documented nor indicated anywhere
You can hold Shift when dragging a node in Scene Tree Dock to keep local transform
If you hold Ctrl while dragging a script file onto a node in scene tree, it will be instantiated as a new node instead of attached
You can drag and drop nodes (1 or more) from Scene Tree into Script Editor to insert their path

37
04_modules/01_thread_pool.md
View File

@ -1,5 +1,7 @@
# Thread pool module
Todo: was merged into core.
A c++ Pandemonium engine module, that will help you with threading.
It can also work if threads are not available (like on the javascript backend), in this case it runs jobs on the
@ -8,11 +10,6 @@ is allocated per frame.
You can access it's setting from the `Project->Project Settings...` menu, in the `ThreadPool` category.
# Pre-built binaries
You can grab a pre-built editor binary from the [Broken Seals](https://github.com/Relintai/broken_seals/releases)
repo, should you want to. It contains all my modules.
# ThreadPoolJob
Contains a job that can run on different threads.
@ -112,33 +109,3 @@ If you have a job, submit it using `add_job`:
MyJob job = MyJob.new()
ThreadPool.add_job(job)
```
It's api is still a bit messy, it will be cleaned up (hopefully very soon).
# Building
1. Get the source code for the engine.
If you want Pandemonium 3.2:
```git clone -b 3.2 https://github.com/Relintai/pandemonium_engine.git pandemonium```
If you want Pandemonium 4.0:
```git clone https://github.com/Relintai/pandemonium_engine.git pandemonium```
[last tested commit](https://github.com/Relintai/pandemonium_engine/commit/b7e10141197fdd9b0dbc4cfa7890329510d36540)
2. Go into Pandemonium's modules directory.
```
cd ./pandemonium/modules/
```
3. Clone this repository
```
git clone https://github.com/Relintai/thread_pool thread_pool
```
4. Build Pandemonium. [Tutorial](https://docs.pandemoniumengine.org/en/latest/development/compiling/index.html)

33
04_modules/02_texture_packer.md
View File

@ -8,39 +8,6 @@ It uses the legacy version of [rectpack2D](https://github.com/TeamHypersomnia/re
It should work on all platforms.
It supports both pandemonium 3.2 and 4.0 (master [last tested commit](https://github.com/Relintai/pandemonium_engine/commit/b7e10141197fdd9b0dbc4cfa7890329510d36540)). Note that since 4.0 is still in very early stages I only
check whether it works from time to time.
# Pre-built binaries
You can grab a pre-built editor binary from the [Broken Seals](https://github.com/Relintai/broken_seals/releases)
repo, should you want to. It contains all my modules.
# Building
1. Get the source code for the engine.
If you want Pandemonium 3.2:
```git clone -b 3.2 https://github.com/Relintai/pandemonium_engine.git pandemonium```
If you want Pandemonium 4.0:
```git clone https://github.com/Relintai/pandemonium_engine.git pandemonium```
2. Go into Pandemonium's modules directory.
```
cd ./pandemonium/modules/
```
3. Clone this repository
```
git clone https://github.com/Relintai/texture_packer texture_packer
```
4. Build Pandemonium. [Tutorial](https://docs.pandemoniumengine.org/en/latest/development/compiling/index.html)
# Features and Usage
## TexturePacker

35
04_modules/03_mesh_utils.md
View File

@ -2,14 +2,6 @@
This is a c++ engine module for the Pandemonium engine, containing my mesh merging utilities.
It supports both pandemonium 3.2 and 4.0 (master [last tested commit](https://github.com/Relintai/pandemonium_engine/commit/b7e10141197fdd9b0dbc4cfa7890329510d36540)). Note that since 4.0 is still in very early stages I only
check whether it works from time to time.
# Pre-built binaries
You can grab a pre-built editor binary from the [Broken Seals](https://github.com/Relintai/broken_seals/releases)
repo, should you want to. It contains all my modules.
# Optional Dependencies
[Mesh Data Resource](https://github.com/Relintai/mesh_data_resource): Support for merged meshes, even in gles2.
@ -31,30 +23,3 @@ Porting is mostly done, but it does needs some debugging (it has a crash if smar
I might just return to using the original FQMS. As if meshes are merged together using `MeshUtils.merge_mesh_array`, or
`bake_mesh_array_uv` the original algorithm will work fine. Still on the fence about it.
# Building
1. Get the source code for the engine.
If you want Pandemonium 3.2:
```git clone -b 3.2 https://github.com/Relintai/pandemonium_engine.git pandemonium```
If you want Pandemonium 4.0:
```git clone https://github.com/Relintai/pandemonium_engine.git pandemonium```
2. Go into Pandemonium's modules directory.
```
cd ./pandemonium/modules/
```
3. Clone this repository
```
git clone https://github.com/Relintai/mesh_utils mesh_utils
```
4. Build Pandemonium. [Tutorial](https://docs.pandemoniumengine.org/en/latest/development/compiling/index.html)

33
04_modules/04_mesh_data_resource.md
View File

@ -9,11 +9,6 @@ The module also comes with importers (gltf, and collada for now), you can import
`https://github.com/Relintai/props`: If present, you also get a prop importer for MeshDataInstances.
`https://github.com/Relintai/mesh_utils`: If present, you get mesh simplification/optimization options at import.
## Pre-built binaries
You can grab a pre-built editor binary from the [Broken Seals](https://github.com/Relintai/broken_seals/releases)
repo, should you want to. It contains all my modules.
## MeshDataResource
The resource that holds mesh and collider data.
@ -39,31 +34,3 @@ if you set it to multiple, you get a MeshDataResourceCollection as the main reso
Since MeshDataResource can hold collider information, these importers can create this for you. There are quite a few options for it:
![Colliders](screenshots/import_2.png)
## Building
1. Get the source code for the engine.
If you want Pandemonium 3.2:
```git clone -b 3.2 https://github.com/Relintai/pandemonium_engine.git pandemonium```
If you want Pandemonium 4.0:
```git clone https://github.com/Relintai/pandemonium_engine.git pandemonium```
[last tested commit for 4.0](https://github.com/Relintai/pandemonium_engine/commit/b7e10141197fdd9b0dbc4cfa7890329510d36540)
2. Go into Pandemonium's modules directory.
```
cd ./pandemonium/modules/
```
3. Clone this repository
```
git clone https://github.com/Relintai/mesh_data_resource mesh_data_resource
```
4. Build Pandemonium. [Tutorial](https://docs.pandemoniumengine.org/en/latest/development/compiling/index.html)

34
04_modules/05_props.md
View File

@ -4,14 +4,6 @@ This is a c++ engine module for the Pandemonium Engine.
It gives you props, and editor utilities to convert scenes to props.
It supports both pandemonium 3.2 and 4.0 (master [last tested commit](https://github.com/Relintai/pandemonium_engine/commit/b7e10141197fdd9b0dbc4cfa7890329510d36540)). Note that since 4.0 is still in very early stages I only
check whether it works from time to time.
# Pre-built binaries
You can grab a pre-built editor binary from the [Broken Seals](https://github.com/Relintai/broken_seals/releases)
repo, should you want to. It contains all my modules.
# Optional Dependencies
[Mesh Data Resource](https://github.com/Relintai/mesh_data_resource): Support for merged meshes, even in gles2.\
@ -67,29 +59,3 @@ You can register new PropDataEntries as processors, should you need to.
You can either click the new "To Prop" button on the menubar of the 3D scene for a quick conversion,
or look into Project->Tools.
# Building
1. Get the source code for the engine.
If you want Pandemonium 3.2:
```git clone -b 3.2 https://github.com/Relintai/pandemonium_engine.git pandemonium```
If you want Pandemonium 4.0:
```git clone https://github.com/Relintai/pandemonium_engine.git pandemonium```
2. Go into Pandemonium's modules directory.
```
cd ./pandemonium/modules/
```
3. Clone this repository
```
git clone https://github.com/Relintai/props props
```
4. Build Pandemonium. [Tutorial](https://docs.pandemoniumengine.org/en/latest/development/compiling/index.html)

34
04_modules/06_props_2d.md
View File

@ -4,14 +4,6 @@ This is a c++ engine module for the Pandemonium Engine.
It gives you props, and editor utilities to convert scenes to props.
It supports both pandemonium 3.2 and 4.0 (master [last tested commit](https://github.com/Relintai/pandemonium_engine/commit/b7e10141197fdd9b0dbc4cfa7890329510d36540)). Note that since 4.0 is still in very early stages I only
check whether it works from time to time.
# Pre-built binaries
You can grab a pre-built editor binary from the [Broken Seals](https://github.com/Relintai/broken_seals/releases)
repo, should you want to. It contains all my modules.
# Optional Dependencies
[Mesh Data Resource](https://github.com/Relintai/mesh_data_resource): Support for merged meshes, even in gles2.\
@ -67,29 +59,3 @@ You can register new Prop2DDataEntries as processors, should you need to.
You can either click the new "To Prop2D" button on the menubar of the 3D scene for a quick conversion,
or look into Project->Tools.
# Building
1. Get the source code for the engine.
If you want Pandemonium 3.2:
```git clone -b 3.2 https://github.com/Relintai/pandemonium_engine.git pandemonium```
If you want Pandemonium 4.0:
```git clone https://github.com/Relintai/pandemonium_engine.git pandemonium```
2. Go into Pandemonium's modules directory.
```
cd ./pandemonium/modules/
```
3. Clone this repository
```
git clone https://github.com/Relintai/props props
```
4. Build Pandemonium. [Tutorial](https://docs.pandemoniumengine.org/en/latest/development/compiling/index.html)

47
04_modules/07_terraman.md
View File

@ -12,14 +12,6 @@ This is an engine module! Which means that you will need to compile it into Pand
You can grab pre-built binaries (even editor + export templates) from the [Broken Seals](https://github.com/Relintai/broken_seals/releases) repo.
## Pandemonium Version Support
3.2 - Will likely work, probably needs changes by now. (TODO check.)\
3.3 - Will more likely work, might need smaller changes by now. (TODO check.)\
3.4 - Should work without any issues. (TODO check.)\
3.x - Works.\
4.0 - Have been fixing support from time to time. Currently it won't build. Mostly done with the fix though.
## Optional Dependencies
`https://github.com/Relintai/texture_packer`: You get access to [TerraLibraryMerger](#voxellibrarymerger) and [TerraLibraryMergerPCM](#voxellibrarymergerpcm). \
@ -179,42 +171,3 @@ If you want to implement your own meshing algorithm you can do so by overriding
TerraMesher works similarly to SurfaceTool, so first you need to set colors, uvs, etc and then call add_vertex.
They won't get reset, so for example if you want all your vertices to have a certain color, you can get away with setting it only once.
## Compiling
First make sure that you can compile pandemonium. See the official docs: https://docs.pandemoniumengine.org/en/3.x/development/compiling/index.html
1. Clone the engine if you haven't already:
If you want Pandemonium 3.x:
```git clone -b 3.x https://github.com/Relintai/pandemonium_engine.git pandemonium```
If you want Pandemonium 4.0:
```git clone https://github.com/Relintai/pandemonium_engine.git pandemonium```
2. go into the modules folder inside the engine's directory:
```cd pandemonium``` \
```cd modules```
3. clone this repository
```git clone https://github.com/Relintai/terraman.git terraman```
(the folder needs to be named terraman!)
4. If you want the optional dependencies run these commands as well:
```git clone https://github.com/Relintai/texture_packer.git texture_packer``` \
```git clone https://github.com/Relintai/mesh_data_resource.git mesh_data_resource```
5. Go up one folder
```cd ..```
6. Compile pandemonium.
For example:
```scons p=x11 t=release_debug tools=yes```

51
04_modules/08_terraman_2d.md
View File

@ -8,18 +8,6 @@ I could have technically implemented all of this into voxelman, as having only h
So I ended up creating this. Everything works the same as in voxelman, but the apis have been simplified to make UX a bit better.
This is an engine module! Which means that you will need to compile it into Pandemonium! [See the compiling section here.](#compiling)
You can grab pre-built binaries (even editor + export templates) from the [Broken Seals](https://github.com/Relintai/broken_seals/releases) repo.
## Pandemonium Version Support
3.2 - Will likely work, probably needs changes by now. (TODO check.)\
3.3 - Will more likely work, might need smaller changes by now. (TODO check.)\
3.4 - Should work without any issues. (TODO check.)\
3.x - Works.\
4.0 - Have been fixing support from time to time. Currently it won't build. Mostly done with the fix though.
## Optional Dependencies
`https://github.com/Relintai/thread_pool`: Threaded chunk generation. Without this terraman is single threaded! \
@ -181,42 +169,3 @@ If you want to implement your own meshing algorithm you can do so by overriding
TerraMesher works similarly to SurfaceTool, so first you need to set colors, uvs, etc and then call add_vertex.
They won't get reset, so for example if you want all your vertices to have a certain color, you can get away with setting it only once.
## Compiling
First make sure that you can compile pandemonium. See the official docs: https://docs.pandemoniumengine.org/en/3.x/development/compiling/index.html
1. Clone the engine if you haven't already:
If you want Pandemonium 3.x:
```git clone -b 3.x https://github.com/Relintai/pandemonium_engine.git pandemonium```
If you want Pandemonium 4.0:
```git clone https://github.com/Relintai/pandemonium_engine.git pandemonium```
2. go into the modules folder inside the engine's directory:
```cd pandemonium``` \
```cd modules```
3. clone this repository
```git clone https://github.com/Relintai/terraman.git terraman```
(the folder needs to be named terraman!)
4. If you want the optional dependencies run these commands as well:
```git clone https://github.com/Relintai/texture_packer.git texture_packer``` \
```git clone https://github.com/Relintai/mesh_data_resource.git mesh_data_resource```
5. Go up one folder
```cd ..```
6. Compile pandemonium.
For example:
```scons p=x11 t=release_debug tools=yes```

50
04_modules/09_voxelman.md
View File

@ -6,17 +6,6 @@ This is an engine module! Which means that you will need to compile it into Pand
You can find a demonstration project (with pre-built binaries) here: https://github.com/Relintai/the_tower
## Pandemonium Version Support
I'm currently mostly using [Terraman](https://github.com/Relintai/terraman) instead of this, so it might get temporarily a bit behind.\
If compile breaks, and I don't notice please report.
3.2 - Will likely work, probably needs changes by now. (TODO check.)\
3.3 - Will more likely work, might need smaller changes by now. (TODO check.)\
3.4 - Should work without any issues. (TODO check.)\
3.x - Works. [last tested commit](6ea58db2d849d9ca0ccee5bc6a6d2b919d404bc1)\
4.0 - Have been fixing support from time to time. Currently it won't build. Mostly done with the fix though.
## Optional Dependencies
`https://github.com/Relintai/texture_packer`: You get access to [VoxelLibraryMerger](#voxellibrarymerger) and [VoxelLibraryMergerPCM](#voxellibrarymergerpcm). \
@ -186,42 +175,3 @@ If you want to implement your own meshing algorithm you can do so by overriding
VoxelMesher works similarly to SurfaceTool, so first you need to set colors, uvs, etc and then call add_vertex.
They won't get reset, so for example if you want all your vertices to have a certain color, you can get away with setting it only once.
## Compiling
First make sure that you can compile pandemonium. See the official docs: https://docs.pandemoniumengine.org/en/3.x/development/compiling/index.html
1. Clone the engine if you haven't already:
If you want Pandemonium 3.x:
```git clone -b 3.x https://github.com/Relintai/pandemonium_engine.git pandemonium```
If you want Pandemonium 4.0:
```git clone https://github.com/Relintai/pandemonium_engine.git pandemonium```
2. go into the modules folder inside the engine's directory:
```cd pandemonium``` \
```cd modules```
3. clone this repository
```git clone https://github.com/Relintai/voxelman.git voxelman```
(the folder needs to be named voxelman!)
4. If you want the optional dependencies run these commands as well:
```git clone https://github.com/Relintai/texture_packer.git texture_packer``` \
```git clone https://github.com/Relintai/mesh_data_resource.git mesh_data_resource```
5. Go up one folder
```cd ..```
6. Compile pandemonium.
For example:
```scons p=x11 t=release_debug tools=yes```

45
04_modules/10_entity_spell_system.md
View File

@ -6,18 +6,6 @@ vendors, interaction, targeting, equipment (+ visuals), loot, crafting, talents,
The module supports networking. It is designed to be authoritative, so players shouldn't be able to cheat by design.
It is a c++ engine module, which means you will need to compile it into pandemonium. (See compiling)
## Pandemonium Version Support
This module is developed with the 3.x branch of pandemonium, usually at the newest revisions.
3.2 - Will likely work, probably needs changes by now. (TODO check.)\
3.3 - Will more likely work, might need smaller changes by now. (TODO check.)\
3.4 - Should work without any issues. (TODO check.)\
3.x - Works.\
4.0 - Have been fixing support from time to time. Currently it won't build on the latest master, and it will take considerable amount of work to get it to work again after the virtual method binding rework. It will be done eventually, but it will take time. [Here](https://github.com/Relintai/pandemonium_engine/commit/b7e10141197fdd9b0dbc4cfa7890329510d36540)'s the last know-to-work commit.
## Project setup tl;dr
### First
@ -565,36 +553,3 @@ https://github.com/Relintai/broken_seals_roguelike
2d:
https://github.com/Relintai/broken_seals_2d.git
## Compiling
First make sure that you can compile pandemonium. See the official docs: https://docs.pandemoniumengine.org/en/3.x/development/compiling/index.html
1. Clone the engine if you haven't already:
If you want Pandemonium 3.x:
```git clone -b 3.x https://github.com/Relintai/pandemonium_engine.git pandemonium```
If you want Pandemonium 4.0:
```git clone https://github.com/Relintai/pandemonium_engine.git pandemonium```
2. go into the modules folder inside the engine's directory"
```cd pandemonium```
```cd modules```
3. clone this repository
```git clone https://github.com/Relintai/entity_spell_system.git entity_spell_system```
(the folder needs to be named entity_spell_system!)
4. Go up one folder
```cd ..```
5. Compile pandemonium.
For example:
```scons p=x11 t=release_debug tools=yes```

21
04_modules/11_skeleton_editor.md
View File

@ -5,24 +5,3 @@ This is a c++ engine module for the Pandemonium engine that contains a modulariz
The original pr is here: https://github.com/Relintai/pandemonium_engine/pull/45699
Tht 3.x version (linked in the pr itself) is here (This is the base for this module): https://github.com/TokageItLab/pandemonium/tree/pose-edit-mode
I'm developing this for pandemonium 3.x, it will probably work on earlier versions though. 4.0 is not supported.
# Building
1. Get the source code for the engine.
```git clone -b 3.x https://github.com/Relintai/pandemonium_engine.git pandemonium```
2. Go into Pandemonium's modules directory.
```
cd ./pandemonium/modules/
```
3. Clone this repository
```
git clone https://github.com/Relintai/skeleton_editor skeleton_editor
```
4. Build Pandemonium. [Tutorial](https://docs.pandemoniumengine.org/en/latest/development/compiling/index.html)

33
04_modules/12_ui_extensions.md
View File

@ -2,14 +2,6 @@
This is a c++ engine module for the Pandemonium engine, containing smaller utilities.
It supports both pandemonium 3.2 and 4.0 (master [last tested commit](https://github.com/Relintai/pandemonium_engine/commit/b7e10141197fdd9b0dbc4cfa7890329510d36540)). Note that since 4.0 is still in very early stages I only
check whether it works from time to time.
# Pre-built binaries
You can grab a pre-built editor binary from the [Broken Seals](https://github.com/Relintai/broken_seals/releases)
repo, should you want to. It contains all my modules.
# TouchButton
A `Control` based button, that handles multitouch properly.
@ -49,30 +41,5 @@ func _ready():
I recommend putting this code into a singleton.
# Building
1. Get the source code for the engine.
If you want Pandemonium 3.2:
```git clone -b 3.2 https://github.com/Relintai/pandemonium_engine.git pandemonium```
If you want Pandemonium 4.0:
```git clone https://github.com/Relintai/pandemonium_engine.git pandemonium```
2. Go into Pandemonium's modules directory.
```
cd ./pandemonium/modules/
```
3. Clone this repository
```
git clone https://github.com/Relintai/ui_extensions ui_extensions
```
4. Build Pandemonium. [Tutorial](https://docs.pandemoniumengine.org/en/latest/development/compiling/index.html)

0
03_usage/02_2d/img/autotile_template_2x2.png → 04_modules/layered_tile_maps/img/autotile_template_2x2.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 226 B

After

Width:  |  Height:  |  Size: 226 B

0
03_usage/02_2d/img/autotile_template_3x3_minimal.png → 04_modules/layered_tile_maps/img/autotile_template_3x3_minimal.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 461 B

After

Width:  |  Height:  |  Size: 461 B

0
03_usage/02_2d/img/autotile_template_3x3_minimal_16.png → 04_modules/layered_tile_maps/img/autotile_template_3x3_minimal_16.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 1.3 KiB

After

Width:  |  Height:  |  Size: 1.3 KiB

0
03_usage/02_2d/img/autotile_template_3x3_minimal_topdown_floor.png → 04_modules/layered_tile_maps/img/autotile_template_3x3_minimal_topdown_floor.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 812 B

After

Width:  |  Height:  |  Size: 812 B

0
03_usage/02_2d/img/autotile_template_3x3_minimal_topdown_walls.png → 04_modules/layered_tile_maps/img/autotile_template_3x3_minimal_topdown_walls.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 769 B

After

Width:  |  Height:  |  Size: 769 B

0
03_usage/02_2d/img/autotile_template_3x3_minimal_topdown_walls_tall.png → 04_modules/layered_tile_maps/img/autotile_template_3x3_minimal_topdown_walls_tall.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 1.8 KiB

After

Width:  |  Height:  |  Size: 1.8 KiB

0
03_usage/02_2d/img/autotile_template_3x3_minimal_topdown_walls_thick.png → 04_modules/layered_tile_maps/img/autotile_template_3x3_minimal_topdown_walls_thick.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 1.1 KiB

After

Width:  |  Height:  |  Size: 1.1 KiB

47
04_modules/tile_maps/01_using_tilemaps.md
View File

@ -1,10 +1,7 @@
# Using TileMaps
Using TileMaps
==============
Introduction
------------
## Introduction
A tilemap is a grid of tiles used to create a game's layout. There are several
benefits to using `TileMap` nodes to design your levels.
@ -17,8 +14,7 @@ the TileMap.
![](img/tileset_draw_atlas.png)
Project setup
-------------
## Project setup
This demo will use the following tiles taken from Kenney's "Abstract Platformer"
art pack. You can find the complete set `here ( https://kenney.nl/assets/abstract-platformer )`
@ -33,8 +29,7 @@ is to import 2D images using an interpolated "filter" mode, which will result in
ugly borders between the tiles. Select the image and click the Import tab. Turn
off `Filter` and click "Reimport". See `doc_import_images` for details.
TileMap node
------------
## TileMap node
Add a new `TileMap` node to the scene. By default, a TileMap
uses a square grid of tiles. You can also use a perspective-based "Isometric" mode
@ -67,8 +62,7 @@ customize your tilemap's behavior:
All of these options can be left at their defaults for this demo.
Creating a TileSet
------------------
## Creating a TileSet
Once you've configured your tilemap, it's time to add a
`TileSet`. A TileSet is a
@ -106,8 +100,7 @@ the node's lock button:
![](img/tile_lock.png)
Collision shapes
----------------
## Collision shapes
If you're making a map that needs collisions - walls, floor, or other obstacles,
for example - then you'll need to add collision shapes to any tiles that you
@ -123,8 +116,7 @@ collision shape appears in light blue:
You can add occlusion and navigation shapes to the tile in the same way.
Atlas tiles
-----------
## Atlas tiles
Rather than adding individual tiles one at a time, you can define a group of
tiles all at once using an atlas. This also allows you to randomly generate
@ -152,8 +144,7 @@ tiles it contains:
In addition to saving time when defining the tiles, this can help by grouping
similar tiles together when you're working with a large number of tiles.
Random tile priorities
~~~~~~~~~~~~~~~~~~~~~~
### Random tile priorities
When drawing with atlas tiles, enabling the "Use priority" option causes tiles
to be selected at random. By default, each tile in the tileset has an equal
@ -162,8 +153,7 @@ priorities for each tile. For example, a tile with priority 2 is twice as
likely to be selected as a tile with priority 1, and a tile with priority 3 is
50% more likely to be selected than a tile with priority 2.
Autotiles
---------
## Autotiles
Autotiles allow you to define a group of tiles, then add rules to control which
tile gets used for drawing based on the content of adjacent cells.
@ -191,8 +181,7 @@ heading. Allowed values are "2x2", "3x3 (minimal)", and "3x3".
All "on" and "off" bits must be satisfied for a bitmask to match, but "ignore"
bits are ignored.
2x2
~~~
### 2x2
In 2x2 mode, each bitmask contains four bits, one for each corner.
@ -223,8 +212,7 @@ Key:
![](img/autotile_template_2x2.png)
3x3 (minimal)
~~~~~~~~~~~~~
### 3x3 (minimal)
In 3x3 (minimal) mode, each bitmask contains 9 bits (4 corners, 4 edges,
1 center). The 4 corner bits work the same as in 2x2 mode.
@ -241,7 +229,6 @@ arrangement that this mode can test for.
Note:
Right-click an image and choose **Save image as…** to save it.
**Template - Generic:**
@ -302,8 +289,7 @@ This means the texture offset should be `Vector2(0, -120)`:
![](img/autotile_template_3x3_minimal_topdown_walls_tall.png)
3x3
~~~
### 3x3
In 3x3 mode, each bitmask contains 9 bits (4 corners, 4 edges, 1 center)
@ -314,15 +300,13 @@ A total of 256 tiles would be needed to provide exactly one bitmask for each
arrangement that this mode can test for.
Disabling autotile
~~~~~~~~~~~~~~~~~~
### Disabling autotile
When using an autotile, it is possible to turn off the autotile behaviour and
select tiles manually, by clicking "Disable Autotile" at the top of the tile
selection window.
Autotile binding
~~~~~~~~~~~~~~~~
### Autotile binding
By default, autotile only checks for adjacent cells filled using the same
autotile. This behaviour can be overridden in order to have autotiles bind to
@ -338,8 +322,7 @@ Note that to use this in the editor, the script should start with a "tool"
declaration, and you may need to close and reload the scene for these changes
to take effect.
Tips and tricks
---------------
## Tips and tricks
- If you're using a `Camera2D` to scroll your level, you
may notice lines appearing between your tiles. To fix this, open Project

BIN
04_modules/tile_maps/img/autotile_template_2x2.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 226 B

BIN
04_modules/tile_maps/img/autotile_template_3x3_minimal.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 461 B

BIN
04_modules/tile_maps/img/autotile_template_3x3_minimal_16.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.3 KiB

BIN
04_modules/tile_maps/img/autotile_template_3x3_minimal_topdown_floor.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 812 B

BIN
04_modules/tile_maps/img/autotile_template_3x3_minimal_topdown_walls.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 769 B

BIN
04_modules/tile_maps/img/autotile_template_3x3_minimal_topdown_walls_tall.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.8 KiB

BIN
04_modules/tile_maps/img/autotile_template_3x3_minimal_topdown_walls_thick.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.1 KiB

14
05_engine_development/01_compiling/02_introduction_to_the_buildsystem.md
View File

@ -66,7 +66,7 @@ To list the available target platforms, use `scons platform=list`:
windows
x11
Please run SCons again and select a valid platform: platform=<string>
Please run SCons again and select a valid platform: platform=&lt;string&gt;
```
To build for a platform (for example, x11), run with the `platform=` (or
@ -77,7 +77,7 @@ To build for a platform (for example, x11), run with the `platform=` (or
```
This will start the build process, which will take a while. If you want
SCons to build faster, use the `-j <cores )` parameter to specify how many
SCons to build faster, use the `-j &lt;cores&gt;` parameter to specify how many
cores will be used for the build. Or leave it using one core, so you
can use your computer for something else :)
@ -94,7 +94,7 @@ The resulting binaries will be placed in the `bin/` subdirectory,
generally with this naming convention:
```
pandemonium.<platform>.[opt].[tools/debug].<architecture>[extension]
pandemonium.&lt;platform&gt;.[opt].[tools/debug].&lt;architecture&gt;[extension]
```
For the previous build attempt, the result would look like this:
@ -132,7 +132,7 @@ run projects but that does not include the editor or the project
manager.
```
scons platform=<platform> tools=yes/no
scons platform=&lt;platform&gt; tools=yes/no
```
## Target
@ -150,7 +150,7 @@ Target controls optimization and debug flags. Each mode means:
checks to run.
```
scons platform=<platform> target=debug/release_debug/release
scons platform=&lt;platform&gt; target=debug/release_debug/release
```
This flag appends the `.debug` suffix (for debug), or `.tools` (for debug
@ -168,7 +168,7 @@ else.
- **default**: Build for the architecture that matches the host platform.
```
scons platform=<platform> bits=default/32/64
scons platform=&lt;platform&gt; bits=default/32/64
```
This flag appends `.32` or `.64` suffixes to resulting binaries when
@ -207,7 +207,7 @@ See also:
## Cleaning generated files
Sometimes, you may encounter an error due to generated files being present. You
can remove them by using `scons --clean <options )`, where `<options )` is the
can remove them by using `scons --clean &lt;options&gt;`, where `&lt;options&gt;` is the
list of build options you've used to build Pandemonium previously.
Alternatively, you can use `git clean -fixd` which will clean build artifacts

3
05_engine_development/01_compiling/04_compiling_for_x11.md
View File

@ -238,8 +238,7 @@ After the build is completed, a new binary with a `.llvm` suffix will be created
It's still recommended to use GCC for production builds as they can be compiled using
link-time optimization, making the resulting binaries smaller and faster.
Using Pyston for faster development
-----------------------------------
## Using Pyston for faster development
You can use `Pyston ( https://www.pyston.org/ )` to run SCons. Pyston is a JIT-enabled
implementation of the Python language (which SCons is written in). It is currently

12
05_engine_development/01_compiling/09_compiling_for_uwp.md
View File

@ -8,8 +8,7 @@ This will likely get reversed eventually.
This page describes how to compile UWP export template binaries from source. If you're looking to export
your project to UWP instead, read `doc_exporting_for_uwp`.
Requirements
------------
## Requirements
- SCons 3.0+ (see `doc_compiling_for_windows` for more details).
- Visual Studio 2017 or later. See `doc_compiling_for_windows` about the
@ -37,8 +36,7 @@ See also:
For a general overview of SCons usage for Pandemonium, see
`doc_introduction_to_the_buildsystem`.
Compiling
---------
## Compiling
You need to open a proper Visual Studio prompt for the target architecture
you want to build. Check `doc_compiling_for_windows` to see how these
@ -58,8 +56,7 @@ Once you're set, run the SCons command similarly to the other platforms:
C:\pandemonium>scons platform=uwp
```
Creating UWP export templates
-----------------------------
## Creating UWP export templates
To export using the editor you need to properly build package the templates.
You need all three architectures with `debug` and `release` templates to
@ -103,8 +100,7 @@ the export templates for - e.g. `3.0.alpha` for the alpha version of Pandemonium
If you don't want to replace the templates, you can set the "Custom Package"
property in the export window.
Running UWP apps with Visual Studio
-----------------------------------
## Running UWP apps with Visual Studio
If you want to debug the UWP port or simply run your apps without packaging
and signing, you can deploy and launch them using Visual Studio. It might be

1
05_engine_development/01_compiling/11_optimizing_for_size.md
View File

@ -1,7 +1,6 @@
# Optimizing a build for size
## Rationale
Sometimes, it is desired to optimize a build for size rather than speed.

11
05_engine_development/02_cpp/01_introduction_to_pandemonium_development.md
View File

@ -1,23 +1,20 @@
Introduction to Pandemonium development
=================================
# Introduction to Pandemonium development
This page is meant to introduce the global organization of Pandemonium Engine's
source code, and give useful tips for extending/fixing the engine on the
C++ side.
Architecture diagram
--------------------
## Architecture diagram
The following diagram describes the architecture used by Pandemonium, from the
core components down to the abstracted drivers, via the scene
structure and the servers.
![](img/architecture_diagram.jpg
![](img/architecture_diagram.jpg)
Debugging the editor with gdb
-----------------------------
## Debugging the editor with gdb
If you are writing or correcting bugs affecting Pandemonium Engine's editor,
remember that the binary will by default run the project manager first,

29
05_engine_development/02_cpp/02_common_engine_methods_and_macros.md
View File

@ -1,14 +1,13 @@
Common engine methods and macros
================================
# Common engine methods and macros
Pandemonium's C++ codebase makes use of dozens of custom methods and macros which are
used in almost every file. This page is geared towards beginner contributors,
but it can also be useful for those writing custom C++ modules.
Print text
----------
## Print text
```
// Prints a message to standard output.
@ -31,8 +30,7 @@ Print text
If you need to add placeholders in your messages, use format strings as
described below.
Format a string
---------------
## Format a string
The `vformat()` function returns a formatted `String`. It behaves
in a way similar to C's `sprintf()`:
@ -51,8 +49,7 @@ in a way similar to C's `sprintf()`:
In most cases, try to use `vformat()` instead of string concatenation as it
makes for more readable code.
Convert an integer or float to a string
---------------------------------------
## Convert an integer or float to a string
This is mainly useful when printing numbers directly.
@ -64,8 +61,7 @@ This is mainly useful when printing numbers directly.
print_line(rtos(123.45));
```
Internationalize a string
-------------------------
## Internationalize a string
There are two types of internationalization in Pandemonium's codebase:
@ -100,8 +96,7 @@ Note:
string will never match the translation as it will have the placeholder
already replaced when it's passed to TranslationServer.
Clamp a value
-------------
## Clamp a value
Pandemonium provides macros for clamping a value with a lower bound (`MAX`), an
upper bound (`MIN`) or both (`CLAMP`):
@ -118,8 +113,7 @@ upper bound (`MIN`) or both (`CLAMP`):
This works with any type that can be compared to other values (like `int` and
`float`).
Microbenchmarking
-----------------
## Microbenchmarking
If you want to benchmark a piece of code but don't know how to use a profiler,
use this snippet:
@ -138,14 +132,12 @@ declaration.
Note:
You may have to `#include "core/os/os.h"` if it's not present already.
When opening a pull request, make sure to remove this snippet as well as the
include if it wasn't there previously.
Get project/editor settings
---------------------------
## Get project/editor settings
There are four macros available for this:
@ -172,8 +164,7 @@ repetition:
It's recommended to use `GLOBAL_DEF`/`EDITOR_DEF` only once per setting and
use `GLOBAL_GET`/`EDITOR_GET` in all other places where it's referenced.
Error macros
------------
## Error macros
Pandemonium features many error macros to make error reporting more convenient.

54
05_engine_development/02_cpp/03_core_types.md
View File

@ -1,7 +1,6 @@
Core types
==========
# Core types
Pandemonium has a rich set of classes and templates that compose its core,
and everything is built upon them.
@ -9,8 +8,7 @@ and everything is built upon them.
This reference will try to list them in order for their better
understanding.
Definitions
-----------
## Definitions
Pandemonium uses the standard C99 datatypes, such as `uint8_t`,
`uint32_t`, `int64_t`, etc. which are nowadays supported by every
@ -31,13 +29,11 @@ many architectures have 4 bytes long wchar_t, where 2 bytes might be
desired. However, by default, this has not been forced and CharType maps
directly to wchar_t.
References:
~~~~~~~~~~~
### References:
- `core/typedefs.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/typedefs.h )`
Memory model
------------
## Memory model
PC is a wonderful architecture. Computers often have gigabytes of RAM,
terabytes of storage and gigahertz of CPU, and when an application needs
@ -70,8 +66,7 @@ be locked to be accessed, and if an allocation runs out of memory, the
pool will be rearranged and compacted on demand. Depending on the need
of the game, the programmer can configure the dynamic memory pool size.
Allocating memory
-----------------
## Allocating memory
Pandemonium has many tools for tracking memory usage in a game, especially
during debug. Because of this, the regular C and C++ library calls
@ -128,14 +123,12 @@ locked until they go out of scope. However, PoolVectors should be used
for small, dynamic memory operations, as read() and write() are too slow for a
large amount of accesses.
References:
~~~~~~~~~~~
### References:
- `core/os/memory.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/os/memory.h )`
- `core/pool_vector.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/pool_vector.cpp )`
Containers
----------
## Containers
Pandemonium provides also a set of common containers:
@ -162,29 +155,25 @@ The Vector<> class also has a few nice features:
- It supports multi-threading, by using atomic operations on the
reference counter.
References:
~~~~~~~~~~~
### References:
- `core/vector.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/vector.h )`
- `core/list.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/list.h )`
- `core/set.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/set.h )`
- `core/map.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/map.h )`
String
------
## String
Pandemonium also provides a String class. This class has a huge amount of
features, full Unicode support in all the functions (like case
operations) and utf8 parsing/extracting, as well as helpers for
conversion and visualization.
References:
~~~~~~~~~~~
### References:
- `core/ustring.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/ustring.h )`
StringName
----------
## StringName
StringNames are like a String, but they are unique. Creating a
StringName from a string results in a unique internal pointer for all
@ -194,42 +183,35 @@ identifier, as comparing them is basically comparing a pointer.
Creation of a StringName (especially a new one) is slow, but comparison
is fast.
References:
~~~~~~~~~~~
### References:
- `core/string_name.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/string_name.h )`
Math types
----------
## Math types
There are several linear math types available in the core/math
directory.
References:
~~~~~~~~~~~
### References:
- `core/math ( https://github.com/Relintai/pandemonium_engine/tree/3.x/core/math )`
NodePath
--------
## NodePath
This is a special datatype used for storing paths in a scene tree and
referencing them fast.
References:
~~~~~~~~~~~
### References:
- `core/node_path.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/node_path.h )`
RID
---
## RID
RIDs are resource IDs. Servers use these to reference data stored in
them. RIDs are opaque, meaning that the data they reference can't be
accessed directly. RIDs are unique, even for different types of
referenced data.
References:
~~~~~~~~~~~
### References:
- `core/rid.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/rid.h )`

15
05_engine_development/02_cpp/04_variant_class.md
View File

@ -1,10 +1,8 @@
Variant class
=============
# Variant class
About
-----
## About
Variant is the most important datatype of Pandemonium, it's the most important
class in the engine. A Variant takes up only 20 bytes and can store
@ -34,13 +32,11 @@ Basically, thanks to the Variant class, writing Pandemonium itself was a much,
much easier task, as it allows for highly dynamic constructs not common
of C++ with little effort. Become a friend of Variant today.
References:
~~~~~~~~~~~
### References:
- `core/variant.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/variant.h )`
Containers: Dictionary and Array
--------------------------------
## Containers: Dictionary and Array
Both are implemented using variants. A Dictionary can match any datatype
used as key to any other datatype. An Array just holds an array of
@ -53,8 +49,7 @@ desired.
Copy-on-write (COW) mode support for containers was dropped with Pandemonium 3.0.
References:
~~~~~~~~~~~
### References:
- `core/dictionary.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/dictionary.h )`
- `core/array.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/array.h )`

59
05_engine_development/02_cpp/05_object_class.md
View File

@ -1,16 +1,12 @@
Object class
============
# Object class
See also:
This page describes the C++ implementation of objects in Pandemonium.
Looking for the Object class reference? `Have a look here.`
General definition
------------------
## General definition
`Object` is the base class for almost everything. Most classes in Pandemonium
inherit directly or indirectly from it. Objects provide reflection and
@ -33,13 +29,11 @@ This makes Objects gain a lot of functionality, like for example
obj2 = Object::cast_to<OtherClass>(obj); // converting between classes, this also works without RTTI enabled.
```
References:
~~~~~~~~~~~
### References:
- `core/object.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/object.h )`
Registering an Object
---------------------
## Registering an Object
ClassDB is a static class that holds the entire list of registered
classes that inherit from Object, as well as dynamic bindings to all
@ -91,13 +85,11 @@ If just adding modules and functionality that is not expected to be
documented as thoroughly, the `D_METHOD()` macro can safely be ignored and a
string passing the name can be passed for brevity.
References:
~~~~~~~~~~~
### References:
- `core/class_db.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/class_db.h )`
Constants
---------
## Constants
Classes often have enums such as:
@ -122,8 +114,7 @@ The constants can also be bound inside `bind_methods`, by using:
BIND_CONSTANT(MODE_SECOND);
```
Properties (set/get)
--------------------
## Properties (set/get)
Objects export properties, properties are useful for the following:
@ -177,8 +168,7 @@ This creates the property using the setter and the getter.
Binding properties using `set`/`get`/`get_property_list`
-----------------------------------------------------------------
## Binding properties using `set`/`get`/`get_property_list`
An additional method of creating properties exists when more flexibility
is desired (i.e. adding or removing properties on context).
@ -198,8 +188,7 @@ call).
This is also a little less efficient since `p_property` must be
compared against the desired names in serial order.
Dynamic casting
---------------
## Dynamic casting
Pandemonium provides dynamic casting between Object-derived classes, for
example:
@ -216,8 +205,7 @@ works fine (although a bit slower) when RTTI is disabled. This is useful
on platforms where a small binary size is ideal, such as HTML5 or
consoles (with low memory footprint).
Signals
-------
## Signals
Objects can have a set of signals defined (similar to Delegates in other
languages). Connecting to them is rather easy:
@ -238,15 +226,13 @@ Adding signals to a class is done in `bind_methods`, using the
ADD_SIGNAL(MethodInfo("been_killed"))
```
Notifications
-------------
## Notifications
All objects in Pandemonium have a `notification`
method that allows it to respond to engine level callbacks that may relate to it.
More information can be found on the `doc_pandemonium_notifications` page.
References
----------
## References
`Reference` inherits from Object and holds a
reference count. It is the base for reference counted object types.
@ -263,13 +249,11 @@ Declaring them must be done using Ref<> template. For example:
`myref` is reference counted. It will be freed when no more Ref<>
templates point to it.
References:
~~~~~~~~~~~
### References:
- `core/reference.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/reference.h )`
Resources:
----------
## Resources:
`Resource` inherits from Reference, so all resources
are reference counted. Resources can optionally contain a path, which
@ -279,13 +263,11 @@ resources can have the same path, attempt to do so will result in an error.
Resources without a path are fine too.
References:
~~~~~~~~~~~
### References:
- `core/resource.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/resource.h )`
Resource loading
----------------
## Resource loading
Resources can be loaded with the ResourceLoader API, like this:
@ -300,13 +282,11 @@ the same time.
- resourceinteractiveloader (TODO)
References:
~~~~~~~~~~~
### References:
- `core/io/resource_loader.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/io/resource_loader.h )`
Resource saving
---------------
## Resource saving
Saving a resource can be done with the resource saver API:
@ -319,7 +299,6 @@ saved as a reference to that resource. Sub resources without a path will
be bundled with the saved resource and assigned sub-IDs, like
`res://someresource.res::1`. This also helps to cache them when loaded.
References:
~~~~~~~~~~~
### References:
- `core/io/resource_saver.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/io/resource_saver.h )`

21
05_engine_development/02_cpp/06_inheritance_class_tree.md
View File

@ -1,29 +1,24 @@
Inheritance class tree
======================
Object
------
# Inheritance class tree
## Object
![](img/Object.png)
Reference
---------
## OReference
![](img/Reference.png)
Control
-------
## OControl
![](img/Control.png)
Node2D
------
## ONode2D
![](img/Node2D.png)
Spatial
-------
## OSpatial
![](img/Spatial.png)
Source files: :download:`tree.zip <files/class_tree.zip )`.
Source files: :download:`tree.zip ( files/class_tree.zip )`.

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

@ -1,10 +1,7 @@
# Custom modules in C++
Custom modules in C++
=====================
Modules
-------
## Modules
Pandemonium allows extending the engine in a modular way. New modules can be
created and then enabled/disabled. This allows for adding new engine
@ -18,8 +15,7 @@ module, and others. As many new modules as desired can be
created and combined. The SCons build system will take care of it
transparently.
What for?
---------
## What for?
While it's recommended that most of a game be written in scripting (as
it is an enormous time saver), it's perfectly possible to use C++
@ -31,11 +27,10 @@ instead. Adding C++ modules can be useful in the following scenarios:
- Porting an existing game.
- Write a whole, new game in C++ because you can't live without C++.
Creating a new module
---------------------
## Creating a new module
Before creating a module, make sure to `download the source code of Pandemonium
and compile it <toc-devel-compiling )`.
and compile it ( toc-devel-compiling )`.
To create a new module, the first step is creating a directory inside
`modules/`. If you want to maintain the module separately, you can checkout
@ -131,7 +126,7 @@ These files should contain the following:
#include "summator.h"
void register_summator_types() {
ClassDB::register_class<Summator>();
ClassDB::register_class&lt;Summator&gt;();
}
void unregister_summator_types() {
@ -225,8 +220,7 @@ Note:
as subclasses. This can be raised to 13 by including the header
file `core/method_bind_ext.gen.inc`.
Using the module
----------------
## Using the module
You can now use your newly created module from any script:
@ -253,11 +247,10 @@ Warning:
template you plan to use, then specify the path to the custom
template in each export preset. Otherwise, you'll get errors when
running the project as the module isn't compiled in the export
template. See the `Compiling <toc-devel-compiling )` pages
template. See the `Compiling ( toc-devel-compiling )` pages
for more information.
Compiling a module externally
-----------------------------
## Compiling a module externally
Compiling a module involves moving the module's sources directly under the
engine's `modules/` directory. While this is the most straightforward way to
@ -309,8 +302,7 @@ See also:
`Introduction to the buildsystem - Custom modules build option ( doc_buildsystem_custom_modules )`.
Improving the build system for development
------------------------------------------
## Improving the build system for development
Warning:
@ -426,8 +418,7 @@ shared module as target in the SCons command:
scons summator_shared=yes platform=x11 bin/libsummator.x11.tools.64.so
```
Writing custom documentation
----------------------------
## Writing custom documentation
Writing documentation may seem like a boring task, but it is highly recommended
to document your newly created module in order to make it easier for users to
@ -477,7 +468,7 @@ Tip:
```
Untracked files:
(use "git add <file>..." to include in what will be committed)
(use "git add &lt;file&gt;..." to include in what will be committed)
doc/classes/MyClass2D.xml
doc/classes/MyClass4D.xml
@ -488,8 +479,8 @@ Tip:
3. Now we can generate the documentation:
We can do this via running Pandemonium's doctool i.e. `pandemonium --doctool <path )`,
which will dump the engine API reference to the given `<path )` in XML format.
We can do this via running Pandemonium's doctool i.e. `pandemonium --doctool &lt;path&gt;`,
which will dump the engine API reference to the given `&lt;path&gt;` in XML format.
In our case we'll point it to the root of the cloned repository. You can point it
to an another folder, and just copy over the files that you need.
@ -497,7 +488,7 @@ to an another folder, and just copy over the files that you need.
Run command:
```
user@host:~/pandemonium/bin$ ./bin/<pandemonium_binary> --doctool .
user@host:~/pandemonium/bin$ ./bin/&lt;pandemonium_binary&gt; --doctool .
```
Now if you go to the `pandemonium/modules/summator/doc_classes` folder, you will see
@ -517,7 +508,7 @@ the things that you previously added. Of course if you point it to your pandemon
folder, make sure you don't lose work by extracting older docs from an older engine build
on top of the newer ones.
Note that if you don't have write access rights to your supplied `<path )`,
Note that if you don't have write access rights to your supplied `&lt;path&gt;`,
you might encounter an error similar to the following:
```
@ -525,10 +516,7 @@ you might encounter an error similar to the following:
At: editor/doc/doc_data.cpp:956
```
Adding custom editor icons
--------------------------
## Adding custom editor icons
Similarly to how you can write self-contained documentation within a module,
you can also create your own custom icons for classes to appear in the editor.
@ -554,8 +542,7 @@ add the following code snippet to `config.py` to override the default path:
return "path/to/icons"
```
Summing up
----------
## Summing up
Remember to:

18
05_engine_development/02_cpp/08_binding_to_external_libraries.md
View File

@ -1,10 +1,8 @@
Binding to external libraries
=============================
# Binding to external libraries
Modules
-------
## Modules
The Summator example in `doc_custom_modules_in_c++` is great for small,
custom modules, but what if you want to use a larger, external library?
@ -75,7 +73,8 @@ need to be created:
register_types.cpp
```
.. important::
Important:
These files must be in the top-level folder of your module (next to your
`SCsub` and `config.py` files) for the module to be registered properly.
@ -128,7 +127,8 @@ installation commands for Linux below, for reference.
sudo apt-get install festvox-don festvox-rablpc16k festvox-kallpc16k festvox-kdlpc16k <-- Installs voices
```
.. important::
Important:
The voices that Festival uses (and any other potential external/3rd-party
resource) all have varying licenses and terms of use; some (if not most) of them may be
be problematic with Pandemonium, even if the Festival Library itself is MIT License compatible.
@ -152,7 +152,8 @@ can link to them instead by adding them as submodules (from within the modules/t
git submodule add https://github.com/festvox/speech_tools
```
.. important::
Important:
Please note that Git submodules are not used in the Pandemonium repository. If
you are developing a module to be merged into the main Pandemonium repository, you should not
use submodules. If your module doesn't get merged in, you can always try to implement
@ -213,8 +214,7 @@ The final module should look like this:
pandemonium/modules/tts/SCsub
```
Using the module
----------------
## Using the module
You can now use your newly created module from any script:

41
05_engine_development/02_cpp/09_custom_pandemonium_servers.md
View File

@ -1,10 +1,8 @@
Custom Pandemonium servers
====================
# Custom Pandemonium servers
Introduction
------------
## Introduction
Pandemonium implements multi-threading as servers. Servers are daemons which
manage data, process it, and push the result. Servers implement the
@ -15,15 +13,13 @@ its RID allocations.
This guide assumes the reader knows how to create C++ modules and Pandemonium
data types. If not, refer to `doc_custom_modules_in_c++`.
References
~~~~~~~~~~~
### References
- `Why does Pandemonium use servers and RIDs? ( https://pandemoniumengine.org/article/why-does-pandemonium-use-servers-and-rids )`
- `Singleton pattern ( https://en.wikipedia.org/wiki/Singleton_pattern )`
- `Mediator pattern ( https://en.wikipedia.org/wiki/Mediator_pattern )`
What for?
---------
## What for?
- Adding artificial intelligence.
- Adding custom asynchronous threads.
@ -32,8 +28,7 @@ What for?
- Adding a custom VoIP protocol.
- And more...
Creating a Pandemonium server
-----------------------
## Creating a Pandemonium server
At minimum, a server must have a static instance, a sleep timer, a thread loop,
an initialization state and a cleanup procedure.
@ -270,11 +265,10 @@ an initialization state and a cleanup procedure.
};
```
Custom managed resource data
----------------------------
## Custom managed resource data
Pandemonium servers implement a mediator pattern. All data types inherit `RID_Data`.
`RID_Owner<MyRID_Data )` owns the object when `make_rid` is called. During debug mode only,
`RID_Owner) MyRID_Data )` owns the object when `make_rid` is called. During debug mode only,
RID_Owner maintains a list of RIDs. In practice, RIDs are similar to writing
object-oriented C code.
@ -312,14 +306,12 @@ object-oriented C code.
}
```
References
~~~~~~~~~~~
### References
- `RID( rid )`
- `core/rid.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/rid.h )`
Registering the class in GDScript
---------------------------------
## Registering the class in GDScript
Servers are allocated in `register_types.cpp`. The constructor sets the static
instance and `init()` creates the managed thread; `unregister_types.cpp`
@ -375,8 +367,7 @@ is used to register the dummy class in GDScript.
- `servers/register_server_types.cpp ( https://github.com/Relintai/pandemonium_engine/blob/master/servers/register_server_types.cpp )`
Bind methods
~~~~~~~~~~~~
### Bind methods
The dummy class binds singleton methods to GDScript. In most cases, the dummy class methods wraps around.
@ -462,8 +453,7 @@ It is possible to emit signals to GDScript by calling the GDScript dummy object.
}
```
MessageQueue
------------
## MessageQueue
In order to send commands into SceneTree, MessageQueue is a thread-safe buffer
to queue set and call methods for other threads. To queue a command, obtain
@ -471,13 +461,11 @@ the target object RID and use either `push_call`, `push_set`, or `push_notificat
to execute the desired behavior. The queue will be flushed whenever either
`SceneTree::idle` or `SceneTree::iteration` is executed.
References:
~~~~~~~~~~~
### References:
- `core/message_queue.cpp ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/message_queue.cpp )`
Summing it up
-------------
## Summing it up
Here is the GDScript sample code:
@ -502,8 +490,7 @@ Here is the GDScript sample code:
print(HilbertHotel.get_bus_info(r_id))
```
Notes
~~~~~
### Notes
- The actual `Hilbert Hotel ( https://en.wikipedia.org/wiki/Hilbert%27s_paradox_of_the_Grand_Hotel )` is impossible.
- Connecting signal example code is pretty hacky.

43
05_engine_development/02_cpp/10_custom_resource_format_loaders.md
View File

@ -1,10 +1,8 @@
Custom resource format loaders
==============================
# Custom resource format loaders
Introduction
------------
## Introduction
ResourceFormatLoader is a factory interface for loading file assets.
Resources are primary containers. When load is called on the same file
@ -14,35 +12,29 @@ loaded resources must be stateless.
This guide assumes the reader knows how to create C++ modules and Pandemonium
data types. If not, refer to this guide `doc_custom_modules_in_c++`.
References
~~~~~~~~~~
### References
- `ResourceLoader( resourceloader )`
- `core/io/resource_loader.cpp ( https://github.com/Relintai/pandemonium_engine/blob/master/core/io/resource_loader.cpp )`
What for?
---------
## What for?
- Adding new support for many file formats
- Audio formats
- Video formats
- Machine learning models
What not?
---------
## What not?
- Raster images
ImageFormatLoader should be used to load images.
References
~~~~~~~~~~
### References
- `core/io/image_loader.h ( https://github.com/Relintai/pandemonium_engine/blob/master/core/io/image_loader.h )`
Creating a ResourceFormatLoader
-------------------------------
## Creating a ResourceFormatLoader
Each file format consist of a data container and a `ResourceFormatLoader`.
@ -105,8 +97,7 @@ read and handle data serialization.
}
```
Creating a ResourceFormatSaver
------------------------------
## Creating a ResourceFormatSaver
If you'd like to be able to edit and save a resource, you can implement a
`ResourceFormatSaver`:
@ -154,8 +145,7 @@ If you'd like to be able to edit and save a resource, you can implement a
}
```
Creating custom data types
--------------------------
## Creating custom data types
Pandemonium may not have a proper substitute within its `doc_core_types`
or managed resources. Pandemonium needs a new registered data type to
@ -258,8 +248,7 @@ Here is an example of creating a custom datatype:
}
```
Considerations
~~~~~~~~~~~~~~
### Considerations
Some libraries may not define certain common routines such as IO handling.
Therefore, Pandemonium call translations are required.
@ -298,15 +287,13 @@ calls into `std::istream`.
};
```
References
~~~~~~~~~~
### References
- `istream ( http://www.cplusplus.com/reference/istream/istream/ )`
- `streambuf ( http://www.cplusplus.com/reference/streambuf/streambuf/?kw=streambuf )`
- `core/io/fileaccess.h ( https://github.com/Relintai/pandemonium_engine/blob/master/core/os/file_access.h )`
Registering the new file format
-------------------------------
## Registering the new file format
Pandemonium registers `ResourcesFormatLoader` with a `ResourceLoader`
handler. The handler selects the proper loader automatically
@ -351,13 +338,11 @@ when `load` is called.
}
```
References
~~~~~~~~~~
### References
- `core/io/resource_loader.cpp ( https://github.com/Relintai/pandemonium_engine/blob/master/core/io/resource_loader.cpp )`
Loading it on GDScript
----------------------
## Loading it on GDScript
Save a file called `demo.json` with the following contents and place it in the
project's root folder:

29
05_engine_development/02_cpp/11_custom_audiostreams.md
View File

@ -1,10 +1,8 @@
Custom AudioStreams
===================
# Custom AudioStreams
Introduction
------------
## Introduction
AudioStream is the base class of all audio emitting objects.
AudioStreamPlayer binds onto an AudioStream to emit PCM data
@ -19,21 +17,18 @@ AudioStream into PCM data.
This guide assumes the reader knows how to create C++ modules. If not, refer to this guide
`doc_custom_modules_in_c++`.
References:
~~~~~~~~~~~
### References:
- `servers/audio/audio_stream.h ( https://github.com/Relintai/pandemonium_engine/blob/master/servers/audio/audio_stream.h )`
- `scene/audio/audioplayer.cpp ( https://github.com/Relintai/pandemonium_engine/blob/master/scene/audio/audio_player.cpp )`
What for?
---------
## What for?
- Binding external libraries (like Wwise, FMOD, etc).
- Adding custom audio queues
- Adding support for more audio formats
Create an AudioStream
---------------------
## Create an AudioStream
An AudioStream consists of three components: data container, stream name,
and an AudioStreamPlayback friend class generator. Audio data can be
@ -113,14 +108,12 @@ Therefore, playback state must be self-contained in AudioStreamPlayback.
}
```
References:
~~~~~~~~~~~
### References:
- `servers/audio/audio_stream.h ( https://github.com/Relintai/pandemonium_engine/blob/master/servers/audio/audio_stream.h )`
Create an AudioStreamPlayback
-----------------------------
## Create an AudioStreamPlayback
AudioStreamPlayer uses `mix` callback to obtain PCM data. The callback must match sample rate and fill the buffer.
@ -228,8 +221,7 @@ Since AudioStreamPlayback is controlled by the audio thread, i/o and dynamic mem
}
```
Resampling
~~~~~~~~~~
### Resampling
Pandemonium's AudioServer currently uses 44100 Hz sample rate. When other sample rates are
needed such as 48000, either provide one or use AudioStreamPlaybackResampled.
@ -277,6 +269,7 @@ query AudioFrames and `get_stream_sampling_rate` to query current mix rate.
AudioStreamPlaybackResampledMyTone();
~AudioStreamPlaybackResampledMyTone();
};
```
```
#include "mytone_audiostream_resampled.h"
@ -343,8 +336,8 @@ query AudioFrames and `get_stream_sampling_rate` to query current mix rate.
}
```
References:
~~~~~~~~~~~
### References:
- `core/math/audio_frame.h ( https://github.com/Relintai/pandemonium_engine/blob/master/core/math/audio_frame.h )`
- `servers/audio/audio_stream.h ( https://github.com/Relintai/pandemonium_engine/blob/master/servers/audio/audio_stream.h )`
- `scene/audio/audioplayer.cpp ( https://github.com/Relintai/pandemonium_engine/blob/master/scene/audio/audio_player.cpp )`

10
05_engine_development/02_cpp/12_macos_debug.md
View File

@ -1,8 +1,7 @@
Debugging on macOS
==================
Debugging Pandemonium editor
----------------------
# Debugging on macOS
## Debugging Pandemonium editor
Attaching a debugger to the signed macOS process requires the "com.apple.security.get-task-allow" entitlement, which is not enabled by default, since apps can't be notarized as long as it is enabled.
If you want to debug an official build of the editor it should be re-signed with the proper entitlements.
@ -38,7 +37,6 @@ Then use the following command to re-sign the editor:
codesign -s - --deep --force --options=runtime --entitlements ./editor.entitlements ./path/to/Pandemonium.app
```
Debugging exported project
--------------------------
## Debugging exported project
To allow debugging, select the `codesign\debugging` (`com.apple.security.get-task-allow`) entitlement during the export. When it is selected, notarization is not supported and should be disabled.

30
05_engine_development/02_cpp/13_using_cpp_profilers.md
View File

@ -1,20 +1,17 @@
Using C++ profilers
===================
# Using C++ profilers
To optimize Pandemonium's performance, you need to know what to optimize first.
To this end, profilers are useful tools.
Note:
There is a built-in GDScript profiler in the editor, but using C++ profiler
may be useful in cases where the GDScript profiler is not accurate enough
or is missing information due to bugs in the profiler.
Recommended profilers
---------------------
## Recommended profilers
- `VerySleepy ( http://www.codersnotes.com/sleepy/ )` (Windows only)
- `HotSpot ( https://github.com/KDAB/hotspot )` (Linux only)
@ -23,8 +20,7 @@ Recommended profilers
These profilers may not be the most powerful or flexible options, but their
standalone operation and limited feature set tends to make them easier to use.
Setting up Pandemonium
----------------
## Setting up Pandemonium
To get useful profiling information, it is **absolutely required** to use a Pandemonium
build that includes debugging symbols. Official binaries do not include debugging
@ -48,26 +44,22 @@ Warning:
after compiling the binaries. Otherwise, you will no longer get useful
profiling information when running a profiler.
Benchmarking startup/shutdown times
-----------------------------------
## Benchmarking startup/shutdown times
If you're looking into optimizing Pandemonium's startup/shutdown performance,
you can tell the profiler to use the `--quit` command line option on the Pandemonium binary.
This will exit Pandemonium just after it finished starting.
The `--quit` option works with `--editor`, `--project-manager` or
`--path <path to project directory )` (which runs a project directly).
`--path &lt;path to project directory&gt;` (which runs a project directly).
See also:
See `doc_command_line_tutorial` for more command line arguments
supported by Pandemonium.
Profiler-specific instructions
------------------------------
## Profiler-specific instructions
VerySleepy
^^^^^^^^^^
#### VerySleepy
- Start the Pandemonium editor or your project first.
If you start the project manager, make sure to edit or run a project first.
@ -83,13 +75,12 @@ VerySleepy
- Once the results window appears, filter the view to remove external modules (such as the graphics driver).
You can filter by module by finding a line whose **Module** matches the Pandemonium
executable name, right-clicking that line then choosing
**Filter Module to <Pandemonium executable name>** in the dropdown that appears.
**Filter Module to &lt;Pandemonium executable name&gt;** in the dropdown that appears.
- Your results window should now look something like this:
![](img/cpp_profiler_verysleepy_results_filtered.png)
HotSpot
^^^^^^^
#### HotSpot
- Open HotSpot. Click **Record Data**:
@ -136,8 +127,7 @@ Note:
This process attachment-based workflow is similar to the one used by VerySleepy.
Xcode Instruments
^^^^^^^^^^^^^^^^^
#### Xcode Instruments
- Open Xcode. Select **Open Developer Tool** - **Instruments** from the **Xcode** app menu:
- Double-click on **Time Profiler** in the **Instruments** window:

16
05_engine_development/02_cpp/configuring_an_ide/01_android_studio.md
View File

@ -1,28 +1,24 @@
Android Studio
==============
# Android Studio
`Android Studio ( https://developer.android.com/studio )` is a free
`JetBrains ( https://www.jetbrains.com/ )` IDE for Android development.
It has a feature-rich editor which supports Java and C/C++. It can be used to
work on Pandemonium's core engine as well as the Android platform codebase.
Importing the project
---------------------
## Importing the project
- From the Android Studio's welcome window select **Open an existing
Android Studio project**.
.. figure:: img/android_studio_setup_project_1.png)
:figclass: figure-w480
:align: center
Android Studio's welcome window.
![figure-w480](img/android_studio_setup_project_1.png)
Android Studio's welcome window.
- Navigate to `<Pandemonium root directory>/platform/android/java` and select the `settings.gradle` file.
- Android Studio will import and index the project.
- To build the project, follow the `compiling instructions <toc-devel-compiling )`.
- To build the project, follow the `compiling instructions ( toc-devel-compiling )`.
If you run into any issues, ask for help in one of
`Pandemonium's community channels ( https://pandemoniumengine.org/community )`.

27
05_engine_development/02_cpp/configuring_an_ide/02_clion.md
View File

@ -1,13 +1,11 @@
CLion
=====
# CLion
`CLion ( https://www.jetbrains.com/clion/ )` is a commercial
`JetBrains ( https://www.jetbrains.com/ )` IDE for C++.
Importing the project
---------------------
## Importing the project
CLion requires a `CMakeLists.txt` file as a project file, which is problematic
for Pandemonium because it uses the SCons buildsystem instead of CMake. However,
@ -21,21 +19,18 @@ which can also be used by CLion.
`CMakeLists.txt` file is located there) and select it (but *not* the
`CMakeLists.txt` file itself), then click **OK**.
.. figure:: img/clion_1_open.png)
:align: center
![](img/clion_1_open.png)
The folder containing the `CMakeLists.txt` file.
The folder containing the `CMakeLists.txt` file.
- If this popup window appears, select **This Window** to open the project:
.. figure:: img/clion_2_this_window.png)
:align: center
![](img/clion_2_this_window.png)
- Choose **Tools > CMake > Change Project Root** from the top menu and select
the Pandemonium root folder.
.. figure:: img/clion_3_change_project_root.png)
:align: center
![](img/clion_3_change_project_root.png)
- You should be now be able to see all the project files. Autocomplete should
work once the project has finished indexing.
@ -43,8 +38,7 @@ which can also be used by CLion.
If you run into any issues, ask for help in one of
`Pandemonium's community channels ( https://pandemoniumengine.org/community )`.
Debugging the project
---------------------
## Debugging the project
Since CLion does not support SCons, you won't be able to compile, launch, and debug Pandemonium from CLion in one step.
You will first need to `compile pandemonium yourself ( https://docs.pandemoniumengine.org/en/stable/development/compiling/index.html )` and run the binary without CLion. You will then be able to debug Pandemonium by using the `Attach to process ( https://www.jetbrains.com/help/clion/attaching-to-local-process.html )` feature.
@ -55,18 +49,15 @@ You will first need to `compile pandemonium yourself ( https://docs.pandemoniume
- In CLion, go to **Run > Attach to Process...**
.. figure:: img/clion_4_select_attach_to_process.png)
:align: center
![](img/clion_4_select_attach_to_process.png)
- Find and Select pandemonium in the list (or type the binary name/Process ID)
.. figure:: img/clion_5_select_pandemonium_process.png)
:align: center
![](img/clion_5_select_pandemonium_process.png)
You can now use the debugging tools from CLion.
Note:
If you run the binary without any arguments, you will only debug the project manager window.
Don't forget to add the `--path path/to/your/pandemonium/project` argument to debug a project.

82
05_engine_development/02_cpp/configuring_an_ide/03_code_blocks.md
View File

@ -1,129 +1,91 @@
Code::Blocks
============
# Code::Blocks
`Code::Blocks ( https://codeblocks.org/ )` is a free, open source, cross platform IDE.
Creating a new project
----------------------
## Creating a new project
From Code::Blocks' main screen, click **Create a new project** or select **File > New > Project...**.
.. figure:: img/code_blocks_file_new_project.png)
:figclass: figure-w480
:align: center
![](img/code_blocks_file_new_project.png)
In the **New from template** window, from **Projects**, select **Empty project**, and click **Go**.
.. figure:: img/code_blocks_new_empty_project.png)
:figclass: figure-w480
:align: center
![](img/code_blocks_new_empty_project.png)
Click Next, to pass the welcome to the new empty project wizard.
.. figure:: img/code_blocks_wizard_welcome.png)
:figclass: figure-w480
:align: center
![](img/code_blocks_wizard_welcome.png)
The project file should be created in the root of the cloned project folder. To achieve this, first, ensure that the **Project title** is the same as the folder name that Pandemonium was cloned into. Unless you cloned the project into a folder with a different name, this will be `pandemonium`.
Second, ensure that the **Folder to create project in** is the folder you ran the Git clone command from, not the `pandemonium` project folder. Confirm that the **Resulting filename** field will create the project file in the root of the cloned project folder.
.. figure:: img/code_blocks_project_title_and_location.png)
:figclass: figure-w480
:align: center
![](img/code_blocks_project_title_and_location.png)
The compiler and configuration settings are managed through **SCons** and will be configured later. However, it's worth deselecting the **Create "Release" configuration** option; so only a single build target is created before clicking **Finish**.
.. figure:: img/code_blocks_compiler_and_configuration.png)
:figclass: figure-w480
:align: center
![](img/code_blocks_compiler_and_configuration.png)
Configuring the build
---------------------
## Configuring the build
The first step is to change the project properties. Right-click on the new project and select **Properties...**.
.. figure:: img/code_blocks_open_properties.png)
:figclass: figure-w480
:align: center
![](img/code_blocks_open_properties.png)
Check the **This is a custom Makefile** property. Click OK to save the changes.
.. figure:: img/code_blocks_project_properties.png)
:figclass: figure-w480
:align: center
![](img/code_blocks_project_properties.png)
The next step is to change the build options. Right-click on the new project and select **Build Options...**.
.. figure:: img/code_blocks_open_build_options.png)
:figclass: figure-w480
:align: center
![](img/code_blocks_open_build_options.png)
Select the **"Make" commands** tab and remove all the existing commands for all the build targets. For each build target enter the **SCons** command for creating the desired build in the **Build project/target** field. The minimum is `scons`. For details on the **SCons** build options, see `doc_introduction_to_the_buildsystem`. It's also useful to add the `scons --clean` command in the **Clean project/target** field to the project's default commmands.
If you're using Windows, all the commands need to be preceded with `cmd /c` to iniitalize the command interpreter.
.. figure:: img/code_blocks_scons_minimum.png)
:figclass: figure-w480
:align: center
![](img/code_blocks_scons_minimum.png)
.. figure:: img/code_blocks_scons_clean.png)
:figclass: figure-w480
:align: center
![](img/code_blocks_scons_clean.png)
Windows example:
.. figure:: img/code_blocks_scons_windows.png)
:figclass: figure-w480
:align: center
!{}(img/code_blocks_scons_windows.png)
Code::Blocks should now be configured to build Pandemonium; so either select **Build > Build**, click the gear button, or press :kbd:`Ctrl + F9`.
Configuring the run
-------------------
## Configuring the run
Once **SCons** has successfully built the desired target, reopen the project **Properties...** and select the **Build targets** tab. In the **Output filename** field, browse to the `bin` folder and select the compiled file.
Deselect the **Auto-generate filename prefix** and **Auto-generate filename extension** options.
.. figure:: img/code_blocks_build_targets.png)
:figclass: figure-w480
:align: center
![](img/code_blocks_build_targets.png)
Code::Blocks should now be configured to run your compiled Pandemonium executable; so either select **Build > Run**, click the green arrow button, or press :kbd:`Ctrl + F10`.
There are two additional points worth noting. First, if required, the **Execution working dir** field can be used to test specific projects, by setting it to the folder containing the `project.pandemonium` file. Second, the **Build targets** tab can be used to add and remove build targets for working with and creating different builds.
Adding files to the project
---------------------------
## Adding files to the project
To add all the Pandemonium code files to the project, right-click on the new project and select **Add files recursively...**.
.. figure:: img/code_blocks_add_files_recursively.png)
:figclass: figure-w480
:align: center
![](img/code_blocks_add_files_recursively.png)
It should automatically select the project folder; so simply click **Open**. By default, all code files are included, so simply click **OK**.
.. figure:: img/code_blocks_select_files.png)
:figclass: figure-w480
:align: center
![](img/code_blocks_select_files.png)
Code style configuration
------------------------
## Code style configuration
Before editing any files, remember that all code needs to comply with the `doc_code_style_guidelines`. One important difference with Pandemonium is the use of tabs for indents. Therefore, the key default editor setting that needs to be changed in Code::Blocks is to enable tabs for indents. This setting can be found by selecting **Settings > Editor**.
.. figure:: img/code_blocks_update_editor_settings.png)
:figclass: figure-w480
:align: center
![](img/code_blocks_update_editor_settings.png)
Under **General Settings**, on the **Editor Settings** tab, under **Tab Options** check **Use TAB character**.
.. figure:: img/code_block_use_tab_character.png)
:figclass: figure-w480
:align: center
![](img/code_block_use_tab_character.png)
That's it. You're ready to start contributing to Pandemonium using the Code::Blocks IDE. Remember to save the project file and the **Workspace**. If you run into any issues, ask for help in one of `Pandemonium's community channels ( https://pandemoniumengine.org/community )`.

55
05_engine_development/02_cpp/configuring_an_ide/04_kdevelop.md
View File

@ -1,34 +1,26 @@
KDevelop
========
# KDevelop
`KDevelop ( https://www.kdevelop.org )` is a free, open source IDE for all desktop platforms.
Importing the project
---------------------
## Importing the project
- From the KDevelop's main screen select **Open Project**.
.. figure:: img/kdevelop_newproject.png)
:figclass: figure-w480
:align: center
![](img/kdevelop_newproject.png)
KDevelop's main screen.
KDevelop's main screen.
- Navigate to the Pandemonium root folder and select it.
- On the next screen, choose **Custom Build System** for the **Project Manager**.
.. figure:: img/kdevelop_custombuild.png)
:figclass: figure-w480
:align: center
![](img/kdevelop_custombuild.png)
- After the project has been imported, open the project configuration by right-clicking
on it in the **Projects** panel and selecting **Open Configuration..** option.
.. figure:: img/kdevelop_openconfig.png)
:figclass: figure-w480
:align: center
![](img/kdevelop_openconfig.png)
- Under **Language Support** open the **Includes/Imports** tab and add the following paths:
@ -42,46 +34,35 @@ Importing the project
corresponding to your current platform
```
.. figure:: img/kdevelop_addincludes.png)
:figclass: figure-w480
:align: center
![](img/kdevelop_addincludes.png)
- Apply the changes.
- Under **Custom Build System** add a new build configuration with the following settings:
+-----------------+------------------------------------------------------------------------------+
| Build Directory | *blank* |
+-----------------+------------------------------------------------------------------------------+
| Enable | **True** |
+-----------------+------------------------------------------------------------------------------+
| Executable | **scons** |
+-----------------+------------------------------------------------------------------------------+
| Arguments | See `doc_introduction_to_the_buildsystem` for a full list of arguments. |
+-----------------+------------------------------------------------------------------------------+
| | |
|-----------------|------------------------------------------------------------------------------|
| Build Directory | *blank* |
| Enable | **True** |
| Executable | **scons** |
| Arguments | See `doc_introduction_to_the_buildsystem` for a full list of arguments. |
.. figure:: img/kdevelop_buildconfig.png)
:figclass: figure-w480
:align: center
![](img/kdevelop_buildconfig.png)
- Apply the changes and close the configuration window.
Debugging the project
---------------------
## Debugging the project
- Select **Run > Configure Launches...** from the top menu.
.. figure:: img/kdevelop_configlaunches.png)
:figclass: figure-w480
:align: center
![](img/kdevelop_configlaunches.png)
- Click **Add** to create a new launch configuration.
- Select **Executable** option and specify the path to your executable located in
the `<Pandemonium root directory>/bin` folder. The name depends on your build configuration,
e.g. `pandemonium.x11.tools.64` for 64-bit X11 platform with `tools` enabled.
.. figure:: img/kdevelop_configlaunches2.png)
:figclass: figure-w480
:align: center
![](img/kdevelop_configlaunches2.png)
If you run into any issues, ask for help in one of
`Pandemonium's community channels ( https://pandemoniumengine.org/community )`.

61
05_engine_development/02_cpp/configuring_an_ide/05_qt_creator.md
View File

@ -1,78 +1,60 @@
Qt Creator
==========
# Qt Creator
`Qt Creator ( https://doc.qt.io/qtcreator/index.html )` is a free, open source IDE for all desktop platforms.
Importing the project
---------------------
## Importing the project
- From the Qt Creator's main screen select **New Project > Import Project > Import Existing Project**.
.. figure:: img/qtcreator-new-project.png)
:figclass: figure-w480
:align: center
![](img/qtcreator-new-project.png)
- Under **Location** select the Pandemonium root folder.
.. figure:: img/qtcreator-set-project-path.png)
:figclass: figure-w480
:align: center
![](img/qtcreator-set-project-path.png)
- Next, you can choose which folders and files will be visible to the project.
While C/C++ files are added automatically, other extensions can be potentially useful:
`*.glsl` for shader files, `*.py` for buildsystem files,
`*.java` for Android platform development, `*.mm` for macOS platform development.
.. figure:: img/qtcreator-apply-import-filter.png)
:figclass: figure-w480
:align: center
![](img/qtcreator-apply-import-filter.png)
Note:
You can change this configuration later by right-clicking on your project
and selecting the **Edit Files...** option.
.. figure:: img/qtcreator-edit-files-menu.png)
:figclass: figure-w480
:align: center
![](img/qtcreator-edit-files-menu.png)
- Finish the import.
- Open the `project_name.includes` file and add a line containing `.` to it
to correctly enable the code completion.
.. figure:: img/qtcreator-project-name-includes.png)
:figclass: figure-w480
:align: center
![](img/qtcreator-project-name-includes.png)
- From the left-side menu select **Projects** and open the **Build** tab.
- Delete the predefined `make` build step.
.. figure:: img/qtcreator-projects-build.png)
:figclass: figure-w480
:align: center
![](img/qtcreator-projects-build.png)
- Click **Add Build Step > Custom Process Step** to add a new build step
with the following settings:
+-----------+------------------------------------------------------------------------------+
| Command | **scons** |
+-----------+------------------------------------------------------------------------------+
| Arguments | See `doc_introduction_to_the_buildsystem` for a full list of arguments. |
+-----------+------------------------------------------------------------------------------+
| | |
|-----------|------------------------------------------------------------------------------|
| Command | **scons** |
| Arguments | See `doc_introduction_to_the_buildsystem` for a full list of arguments. |
.. figure:: img/qtcreator-set-scons-command.png)
:figclass: figure-w480
:align: center
![](img/qtcreator-set-scons-command.png)
Note:
If the build fails with `Could not start process "scons"`, it can mean that `scons`
is not in your `PATH` environment variable. In this case, you'll have to specify the
full path to the SCons binary.
Debugging the project
---------------------
## Debugging the project
- From the left-side menu select **Projects** and open the **Run** tab.
- Under **Executable** specify the path to your executable located in
@ -82,32 +64,25 @@ Debugging the project
- If you want to run a specific project, specify its root folder under **Working directory**.
- If you want to run the editor, add `-e` to the **Command line arguments** field.
.. figure:: img/qtcreator-run-command.png)
:figclass: figure-w480
:align: center
![](img/qtcreator-run-command.png)
To learn more about command line arguments, refer to the
`command line tutorial ( doc_command_line_tutorial )`.
Code style configuration
------------------------
## Code style configuration
Developers must follow the project's `code style ( doc_code_style_guidelines )`
and the IDE should help them follow it. By default, Qt Creator uses spaces
for indentation which doesn't match the Pandemonium code style guidelines. You can
change this behavior by changing the **Code Style** in **Tools > Options > C++**.
.. figure:: img/qtcreator-options-cpp.png)
:figclass: figure-w480
:align: center
![](img/qtcreator-options-cpp.png)
Click on **Edit** to change the current settings, then click on
**Copy Built-in Code Style** button to set a new code style. Set a name for it
(e.g. Pandemonium) and change the Tab policy to be **Tabs Only**.
.. figure:: img/qtcreator-edit-codestyle.png)
:figclass: figure-w480
:align: center
![](img/qtcreator-edit-codestyle.png)
If you run into any issues, ask for help in one of
`Pandemonium's community channels ( https://pandemoniumengine.org/community )`.

22
05_engine_development/02_cpp/configuring_an_ide/06_visual_studio.md
View File

@ -1,15 +1,13 @@
Visual Studio
=============
# Visual Studio
`Visual Studio Community ( https://visualstudio.microsoft.com )` is a Windows-only IDE
by `Microsoft ( https://microsoft.com )` that's free for non-commercial use.
It has many useful features, such as memory view, performance view, source
control and more.
Importing the project
---------------------
## Importing the project
Visual Studio requires a solution file to work on a project. While Pandemonium does not come
with the solution file, it can be generated using SCons.
@ -21,14 +19,13 @@ with the solution file, it can be generated using SCons.
- Use the **Build** top menu to build the project.
Warning:
Visual Studio must be configured with the C++ package. It can be selected
in the intaller:
.. figure:: img/vs_1_install_cpp_package.png)
:align: center
![](img/vs_1_install_cpp_package.png)
Debugging the project
---------------------
## Debugging the project
Visual Studio features a powerful debugger. This allows the user to examine Pandemonium's
source code, stop at specific points in the code, inspect the current execution context,
@ -42,16 +39,14 @@ project manager opens a project, the initial process is terminated and the debug
- To configure the launch options to use with the debugger use **Project > Properties**
from the top menu:
.. figure:: img/vs_2_project_properties.png)
:align: center
![](img/vs_2_project_properties.png)
- Open the **Debugging** section and under **Command Arguments** add two new arguments:
the `-e` flag opens the editor instead of the project manager, and the `--path` argument
tells the executable to open the specified project (must be provided as an *absolute* path
to the project root, not the `project.pandemonium` file).
.. figure:: img/vs_3_debug_command_line.png)
:align: center
![](img/vs_3_debug_command_line.png)
To learn more about command line arguments, refer to the
`command line tutorial ( doc_command_line_tutorial )`.
@ -62,8 +57,7 @@ process using **Debug > Attach to Process...** menu.
To check that everything is working, put a breakpoint in `main.cpp` and press :kbd:`F5` to
start debugging.
.. figure:: img/vs_4_debugging_main.png)
:align: center
![](img/vs_4_debugging_main.png)
If you run into any issues, ask for help in one of
`Pandemonium's community channels ( https://pandemoniumengine.org/community )`.

31
05_engine_development/02_cpp/configuring_an_ide/07_visual_studio_code.md
View File

@ -1,13 +1,11 @@
Visual Studio Code
==================
# Visual Studio Code
`Visual Studio Code ( https://code.visualstudio.com )` is a free cross-platform code editor
by `Microsoft ( https://microsoft.com )` (not to be confused with `doc_configuring_an_ide_vs`).
Importing the project
---------------------
## Importing the project
- Make sure the C/C++ extension is installed. You can find instructions in
the `official documentation ( https://code.visualstudio.com/docs/languages/cpp )`.
@ -18,18 +16,15 @@ Importing the project
**File > Open Folder...**.
- Press :kbd:`Ctrl + Shift + P` to open the command prompt window and enter *Configure Task*.
.. figure:: img/vscode_configure_task.png)
:align: center
![](img/vscode_configure_task.png)
- Select the **Create tasks.json file from template** option.
.. figure:: img/vscode_create_tasksjson.png)
:align: center
![](img/vscode_create_tasksjson.png)
- Then select **Others**.
.. figure:: img/vscode_create_tasksjson_others.png)
:align: center
![](img/vscode_create_tasksjson_others.png)
- Within the `tasks.json` file find the `"tasks"` array and add a new section to it:
@ -66,25 +61,21 @@ js Windows
}
```
.. figure:: img/vscode_3_tasks.json.png)
:figclass: figure-w480
:align: center
![](img/vscode_3_tasks.json.png)
An example of a filled out `tasks.json`.
An example of a filled out `tasks.json`.
Arguments can be different based on your own setup and needs. See
`doc_introduction_to_the_buildsystem` for a full list of arguments.
Debugging the project
---------------------
## Debugging the project
To run and debug the project you need to create a new configuration in the `launch.json` file.
- Press :kbd:`Ctrl + Shift + D` to open the Run panel.
- If `launch.json` file is missing you will be prompted to create a new one.
.. figure:: img/vscode_1_create_launch.json.png)
:align: center
![](img/vscode_1_create_launch.json.png)
- Select **C++ (GDB/LLDB)**. There may be another platform specific option here. If selected,
adjust the configuration example provided accordingly.
@ -159,9 +150,7 @@ js Windows
}
```
.. figure:: img/vscode_2_launch.json.png)
:figclass: figure-w480
:align: center
![](img/vscode_2_launch.json.png)
An example of a filled out `launch.json`.

55
05_engine_development/02_cpp/configuring_an_ide/08_xcode.md
View File

@ -1,47 +1,35 @@
Xcode
=====
# Xcode
`Xcode ( https://developer.apple.com/xcode )` is a free macOS-only IDE. You can
download it from the Mac App Store.
Importing the project
---------------------
## Importing the project
- From Xcode's main screen create a new project using the **Other > External Build System** template.
.. figure:: img/xcode_1_create_external_build_project.png)
:figclass: figure-w480
:align: center
![](img/xcode_1_create_external_build_project.png)
- Open your build targets from the **Targets** section and select the **Info** tab.
- Fill out the form with the following settings:
+------------+------------------------------------------------------------------------------+
| Build Tool | A full path to the **scons** executable, e.g. **/usr/local/bin/scons** |
+------------+------------------------------------------------------------------------------+
| Arguments | See `doc_introduction_to_the_buildsystem` for a full list of arguments. |
+------------+------------------------------------------------------------------------------+
| Directory | A full path to the Pandemonium root folder |
+------------+------------------------------------------------------------------------------+
| | |
|------------|------------------------------------------------------------------------------|
| Build Tool | A full path to the **scons** executable, e.g. **/usr/local/bin/scons** |
| Arguments | See `doc_introduction_to_the_buildsystem` for a full list of arguments. |
| Directory | A full path to the Pandemonium root folder |
.. figure:: img/xcode_2_configure_scons.png)
:figclass: figure-w480
:align: center
![](img/xcode_2_configure_scons.png)
- Add a Command Line Tool target which will be used for indexing the project by
choosing **File > New > Target...**.
.. figure:: img/xcode_3_add_new_target.png)
:figclass: figure-w480
:align: center
![](img/xcode_3_add_new_target.png)
- Select **OS X > Application > Command Line Tool**.
.. figure:: img/xcode_4_select_command_line_target.png)
:figclass: figure-w480
:align: center
![](img/xcode_4_select_command_line_target.png)
Note:
Name it something so you know not to compile with this target (e.g. `PandemoniumXcodeIndex`).
@ -54,23 +42,18 @@ Note:
- Add the Pandemonium source to the project by dragging and dropping it into the project file browser.
- Uncheck **Create external build system project**.
.. figure:: img/xcode_5_after_add_pandemonium_source_to_project.png)
:figclass: figure-w480
:align: center
![](img/xcode_5_after_add_pandemonium_source_to_project.png)
- Next select **Create groups** for the **Added folders** option and check *only*
your command line indexing target in the **Add to targets** section.
.. figure:: img/xcode_6_after_add_pandemonium_source_to_project_2.png)
:figclass: figure-w480
:align: center
![](img/xcode_6_after_add_pandemonium_source_to_project_2.png)
- Xcode will now index the files. This may take a few minutes.
- Once Xcode is done indexing, you should have jump-to-definition,
autocompletion, and full syntax highlighting.
Debugging the project
---------------------
## Debugging the project
To enable debugging support you need to edit the external build target's build and run schemes.
@ -85,17 +68,13 @@ To enable debugging support you need to edit the external build target's build a
ln -f ${PROJECT_DIR}/pandemonium/bin/pandemonium.osx.tools.64 ${PROJECT_DIR}/pandemonium/bin/pandemonium
```
.. figure:: img/xcode_7_setup_build_post_action.png)
:figclass: figure-w480
:align: center
![](img/xcode_7_setup_build_post_action.png)
- Build the external build target.
- Open the scheme editor again and select **Run**.
.. figure:: img/xcode_8_setup_run_scheme.png)
:figclass: figure-w480
:align: center
![](img/xcode_8_setup_run_scheme.png)
- Set the **Executable** to the file you linked in your post-build action script.
- Check **Debug executable**.

0
05_engine_development/02_cpp/configuring_an_ide/img/clion_5_select_godot_process.png → 05_engine_development/02_cpp/configuring_an_ide/img/clion_5_select_pandemonium_process.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 9.1 KiB

After

Width:  |  Height:  |  Size: 9.1 KiB

0
05_engine_development/02_cpp/configuring_an_ide/img/xcode_5_after_add_godot_source_to_project.png → 05_engine_development/02_cpp/configuring_an_ide/img/xcode_5_after_add_pandemonium_source_to_project.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 8.3 KiB

After

Width:  |  Height:  |  Size: 8.3 KiB

0
05_engine_development/02_cpp/configuring_an_ide/img/xcode_6_after_add_godot_source_to_project_2.png → 05_engine_development/02_cpp/configuring_an_ide/img/xcode_6_after_add_pandemonium_source_to_project_2.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 6.6 KiB

After

Width:  |  Height:  |  Size: 6.6 KiB

19
05_engine_development/03_editor/01_introduction_to_editor_development.md
View File

@ -1,7 +1,5 @@
Introduction to editor development
==================================
# Introduction to editor development
On this page, you will learn:
@ -13,25 +11,22 @@ To create editor plugins in GDScript, see `doc_making_plugins` instead.
See also:
If you are new to Pandemonium, we recommended you to read
`doc_pandemonium_design_philosophy` before continuing. Since the Pandemonium editor
is a Pandemonium project written in C++, much of the engine's philosophy applies
to the editor.
Technical choices
-----------------
## Technical choices
The Pandemonium editor is drawn using Pandemonium's renderer and
`UI system <toc-gui-basics )`. It does *not* rely on a toolkit
`UI system ( toc-gui-basics )`. It does *not* rely on a toolkit
such as GTK or Qt. This is similar in spirit to software like Blender.
While using toolkits makes it easier to achieve a "native" appearance, they are
also quite heavy and their licensing is not compatible with Pandemonium's.
The editor is fully written in C++. It can't contain any GDScript or C# code.
Directory structure
-------------------
## Directory structure
The editor's code is fully self-contained in the
`editor/ ( https://github.com/Relintai/pandemonium_engine/tree/master/editor )` folder
@ -57,8 +52,7 @@ Some important files in the editor are:
Where the 3D editor gizmos are defined and drawn.
This file doesn't have a 2D counterpart as 2D gizmos are drawn by the nodes themselves.
Editor dependencies in `scene/` files
---------------------------------------
## Editor dependencies in `scene/` files
When working on an editor feature, you may have to modify files in
Pandemonium's GUI nodes, which you can find in the `scene/` folder.
@ -80,8 +74,7 @@ Currently, there are some dependencies to `editor/` includes in `scene/`
files, but
`they are in the process of being removed ( https://github.com/Relintai/pandemonium_engine/issues/29730 )`.
Development tips
----------------
## Development tips
To iterate quickly on the editor, we recommend to set up a test project and
`open it from the command line ( doc_command_line_tutorial )` after compiling

21
05_engine_development/03_editor/02_creating_icons.md
View File

@ -1,15 +1,13 @@
Editor icons
============
# Editor icons
When a new class is created and exposed to scripting, the editor's interface
will display it with a default icon representing the base class it inherits
from. In most cases, it's still recommended to create icons for new classes to
improve the user experience.
Creating icons
~~~~~~~~~~~~~~
### Creating icons
To create new icons, you first need a vector graphics editor installed.
For instance, you can use the open source `Inkscape ( https://inkscape.org/ )` editor.
@ -33,8 +31,7 @@ repository's `editor/icons` folder. The icon name should match the intended
name in a case-sensitive manner. For example, to create an icon for
CPUParticles2D, name the file `CPUParticles2D.svg`.
Color conversion for light editor themes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
### Color conversion for light editor themes
If the user has configured their editor to use a light theme, Pandemonium will
convert the icon's colors based on a
@ -43,8 +40,7 @@ This is to ensure the icon always displays with a sufficient contrast rate.
Try to restrict your icon's color palette to colors found in the list above.
Otherwise, your icon may become difficult to read on a light background.
Icon optimization
~~~~~~~~~~~~~~~~~
### Icon optimization
Because the editor renders SVGs once at load time, they need to be small
in size so they can be efficiently parsed. Editor icons must be first
@ -74,8 +70,7 @@ Note:
recommended to keep the source SVG around if you need to make further
changes.
Integrating and sharing the icons
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
### Integrating and sharing the icons
If you're contributing to the engine itself, you should make a pull request to
add optimized icons to `editor/icons` in the main repository. Recompile the
@ -89,8 +84,7 @@ as they can be self-contained.
For specific instructions on how to create module icons, refer to
`Creating custom module icons( doc_custom_module_icons )`.
Troubleshooting
~~~~~~~~~~~~~~~
### Troubleshooting
If icons don't appear in the editor, make sure that:
@ -99,7 +93,6 @@ If icons don't appear in the editor, make sure that:
2. `modules/svg` is enabled (it should be enabled by default). Without it,
icons won't appear in the editor at all.
References
~~~~~~~~~~
### References
- `editor/icons ( https://github.com/Relintai/pandemonium_engine/tree/master/editor/icons )`

21
05_engine_development/03_editor/03_editor_style_guide.md
View File

@ -1,10 +1,8 @@
Editor style guide
==================
# Editor style guide
Introduction
------------
## Introduction
Thanks for your interest in contributing to the Pandemonium editor!
@ -12,8 +10,7 @@ This page describes the grammar and writing style used throughout the Pandemoniu
editor. Following this style guide will help your contribution get merged faster
since there will be fewer review steps required.
Writing style
-------------
## Writing style
- **Write messages (errors, warnings, ...) as full sentences.** They should start
with an uppercase letter and end with a period.
@ -32,8 +29,7 @@ See also:
Try to follow the `doc_docs_writing_guidelines` in addition to the
guidelines outlined above.
Button and menu texts
---------------------
## Button and menu texts
Capitalize text in buttons and menu actions:
@ -45,8 +41,7 @@ If a menu action opens a modal dialog, suffix it with an ellipsis (`...`).
- **Good:** *Editor Settings...*
- **Bad:** *Editor Settings*
Inspector sections
------------------
## Inspector sections
In general, don't create sections that contain less than 3 items. Sections that
contain few items make it difficult to navigate the inspector, while missing the
@ -57,8 +52,7 @@ There are some valid exceptions for this, such as material features in
This advice also applies to the Project Settings and Editor Settings.
Inspector performance hints
---------------------------
## Inspector performance hints
Enum properties that noticeably impact performance should have a performance
hint associated. The hint should refer to the *absolute* performance impact,
@ -81,8 +75,7 @@ and "Slow" from the list above.
If you're adding a new enum, its values should be ordered from the fastest
option to the slowest option.
Tooltips
--------
## Tooltips
Consider adding tooltips whenever the action performed by a button or menu
action isn't obvious. You can also provide additional context or highlight

39
05_engine_development/04_file_formats/01_tscn.md
View File

@ -1,7 +1,6 @@
TSCN file format
================
# TSCN file format
The TSCN (text scene) file format represents a single scene tree inside
Pandemonium. Unlike binary SCN files, TSCN files have the advantage of being mostly
@ -19,8 +18,7 @@ For those looking for a complete description, the parsing is handled in the file
`resource_format_text.cpp ( https://github.com/Relintai/pandemonium_engine/blob/master/scene/resources/resource_format_text.cpp )`
in the `ResourceFormatLoaderText` class.
File structure
--------------
## File structure
There are five main sections inside the TSCN file:
@ -45,8 +43,7 @@ should start with `[ext_resource .....]`.
A TSCN file may contain single-line comments starting with a semicolon (`;`).
However, comments will be discarded when saving the file using the Pandemonium editor.
Entries inside the file
~~~~~~~~~~~~~~~~~~~~~~~
### Entries inside the file
A heading looks like
`[<resource_type> key=value key=value key=value ...]`
@ -66,8 +63,7 @@ so on. For example, a spatial node looks like:
transform=Transform( 1.0, 0.0, 0.0 ,0.0, 1.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0 )
```
The scene tree
--------------
## The scene tree
The scene tree is made up of… nodes! The heading of each node consists of
its name, parent and (most of the time) a type. For example
@ -133,8 +129,7 @@ save a file with that node in it. Some example nodes are:
far = 100.0
```
NodePath
~~~~~~~~
### NodePath
A tree structure is not enough to represent the whole scene. Pandemonium uses a
`NodePath(Path/To/Node)` structure to refer to another node or attribute of
@ -158,8 +153,7 @@ the node anywhere in the scene tree. For instance, MeshInstance uses
...
```
Skeleton
~~~~~~~~
### Skeleton
The Skeleton node inherits the Spatial node, but also may have a list of bones
described in key-value pairs in the format `bones/Id/Attribute=Value`. The
@ -199,8 +193,7 @@ Here's an example of a skeleton node with two bones:
bones/1/bound_children = [ ]
```
BoneAttachment
~~~~~~~~~~~~~~
### BoneAttachment
BoneAttachment node is an intermediate node to describe some node being parented
to a single bone in a Skeleton node. The BoneAttachment has a
@ -230,8 +223,7 @@ An example of one MeshInstance parented to a bone in Skeleton:
transform = Transform(1.0, 0.0, 0.0, 0.0, 1.86265e-09, 1.0, 0.0, -1.0, 0.0, 0.0219986, -0.0343127, 2.25595)
```
AnimationPlayer
~~~~~~~~~~~~~~~
### AnimationPlayer
AnimationPlayer works as an animation library. It stores animations listed in
the format `anim/Name=SubResource(ResourceId)`; each line refers to an
@ -251,8 +243,7 @@ AnimationPlayer. The root node is stored as
blend_times = [ ]
```
Resources
---------
## Resources
Resources are components that make up the nodes. For example, a MeshInstance
node will have an accompanying ArrayMesh resource. The ArrayMesh resource
@ -267,8 +258,7 @@ the same ID for both an internal and external resource.
For example, to refer to the resource `[ext_resource id=3 type="PackedScene"
path=....]`, you would use `ExtResource(3)`.
External resources
~~~~~~~~~~~~~~~~~~
### External resources
External resources are links to resources not contained within the TSCN file
itself. An external resource consists of a path, a type and an ID.
@ -288,8 +278,7 @@ Like TSCN files, a TRES file may contain single-line comments starting with a
semicolon (`;`). However, comments will be discarded when saving the resource
using the Pandemonium editor.
Internal resources
~~~~~~~~~~~~~~~~~~
### Internal resources
A TSCN file can contain meshes, materials and other data. These are contained in
the *internal resources* section of the file. The heading for an internal
@ -313,8 +302,7 @@ Unfortunately, documentation on the formats for these subresources isn't
complete. Some examples can be found by inspecting saved resource files, but
others can only be found by looking through Pandemonium's source.
ArrayMesh
~~~~~~~~~
### ArrayMesh
ArrayMesh consists of several surfaces, each in the format `surface\Index={}`.
Each surface is a set of vertices and a material.
@ -367,8 +355,7 @@ An example of ArrayMesh:
}
```
Animation
~~~~~~~~~
### Animation
An animation resource consists of tracks. Besides, it has `length`, `loop`
and `step` applied to all the tracks.

18
06_community/01_tutorials.md
View File

@ -1,14 +1,12 @@
Tutorials and resources
=======================
# Tutorials and resources
This is a list of third-party tutorials and resources created by the Pandemonium community. For resources, remember that there is the official `Pandemonium Asset Library ( https://pandemoniumengine.org/asset-library/asset )` full of official and community resources too! Also, have a look at this `huge list over at Reddit ( https://www.reddit.com/r/pandemonium/comments/an0iq5/pandemonium_tutorials_list_of_video_and_written/ )`.
Think there is something missing here? Feel free to submit a `Pull Request ( https://github.com/Relintai/pandemonium_engine-docs/blob/master/community/tutorials.rst )` as always.
Where to start
--------------
## Where to start
The Pandemonium video tutorials by `GDQuest ( https://www.youtube.com/channel/UCxboW7x0jZqFdvMdCFKTMsQ/playlists )`, `Game from Scratch ( https://www.youtube.com/watch?v=iDEcP8Mc-7s&list=PLS9MbmO_ssyDk79j9ewONxV88fD5e_o5d )` and `KidsCanCode ( https://www.youtube.com/channel/UCNaPQ5uLX5iIEHUCLmfAgKg/playlists )` are well-regarded in the community and often recommended as a gentle introduction to beginners.
@ -20,8 +18,7 @@ GDQuest's *Learn GDScript From Zero* is a free and open source interactive tutor
Some tutorials mentioned below provide more advanced tutorials, e.g. on 3D or shaders.
Video tutorials
---------------
## Video tutorials
- `Pandemonium Tutorials ( https://www.youtube.com/channel/UCnr9ojBEQGgwbcKsZC-2rIg )` (2D, GDScript, Programming Basics).
- `Emilio ( https://www.youtube.com/channel/UC9DR22-qohBDtZ74R3FxOZg )` (2D, GDScript and VisualScript).
@ -46,22 +43,19 @@ Video tutorials
- `Garbaj ( https://www.youtube.com/c/Garbaj/ )` (3D, GDScript).
- `Kasper Frandsen ( https://www.youtube.com/c/KasperFrandsen/ )` (3D, Shaders).
Text tutorials
--------------
## Text tutorials
- `FinepointCGI website by Mitch ( http://finepointcgi.io/ )`
- `GDScript website by Andrew Wilkes ( https://gdscript.com )`
- `Pandemonium Recipes by KidsCanCode ( http://pandemoniumrecipes.com/ )`
- `Steincodes ( https://steincodes.tumblr.com )`
Devlogs
-------
## Devlogs
- `Andrea Catania (Physics & AI) ( https://www.youtube.com/channel/UCm4RuvYtgpgFDTCgaEUT5uQ/videos )`
- `Bastiaan Olij (AR & VR) ( https://www.youtube.com/channel/UCrbLJYzJjDf2p-vJC011lYw/videos )`
Resources
---------
## Resources
- `awesome-pandemonium: A curated list of free/libre plugins, scripts and add-ons ( https://github.com/pandemoniumengine/awesome-pandemonium )`
- `Zeef Pandemonium Engine: A curated directory of resources by Andre Schmitz ( https://pandemonium-engine.zeef.com/andre.antonio.schmitz )`

77
06_community/contributing/01_introduction.md
View File

@ -1,5 +1,5 @@
Contributing
============
# Contributing
Everyone is most welcome to contribute to Pandemonium. Here are some ways in which you
can contribute to the project:
@ -11,73 +11,30 @@ can contribute to the project:
- Reporting issues or `writing detailed proposals
( https://github.com/Relintai/pandemonium_engine-proposals/ )`.
Getting started
---------------
## Getting started
You would like to contribute but you don't know how or what to do? You can get
answers below.
.. toctree::
:maxdepth: 1
:name: toc-community-getting-started
ways_to_contribute
Contributing to the engine
--------------------------
## Contributing to the engine
The guides below explain how to contribute to the engine's core. You will learn
about the code style, the contribution workflow, and more.
.. toctree::
:maxdepth: 1
:name: toc-community-contributing-to-the-engine
best_practices_for_engine_contributors
pr_workflow
testing_pull_requests
bisecting_regressions
bug_triage_guidelines
code_style_guidelines
cpp_usage_guidelines
Writing documentation
---------------------
## Writing documentation
We always need help to improve the documentation, be it the class reference or
the manual. Below, you can find our content and writing guidelines and
concrete guides to make changes to the documentation.
Guidelines
~~~~~~~~~~
### Guidelines
Here are the principles and guidelines we strive to follow to write accessible
documentation.
.. toctree::
:maxdepth: 1
:name: toc-community-writing-guidelines
### Writing the manual
content_guidelines
docs_writing_guidelines
documentation_guidelines
Writing the manual
~~~~~~~~~~~~~~~~~~
.. toctree::
:maxdepth: 1
:name: toc-community-documentation
contributing_to_the_documentation
building_the_manual
Class reference guides
~~~~~~~~~~~~~~~~~~~~~~
### Class reference guides
The pages below focus on the class reference.
@ -86,24 +43,8 @@ the `pandemonium repository ( https://github.com/Relintai/pandemonium_engine )`.
to write it, so the process to contribute to the class reference differs from
writing the online manual.
.. toctree::
:maxdepth: 1
:name: toc-community-class-reference
updating_the_class_reference
class_reference_writing_guidelines
Translating the documentation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
### Translating the documentation
The community is always working hard on making Pandemonium and its documentation
available to more people. Localizing the documentation is a colossal and ongoing
effort you can be part of.
.. toctree::
:maxdepth: 1
:name: toc-community-localization
editor_and_docs_localization

21
06_community/contributing/02_ways_to_contribute.md
View File

@ -1,7 +1,6 @@
Ways to contribute
==================
# Ways to contribute
Pandemonium Engine is a non-profit, community-driven free and open source project.
Almost all (but our lead dev Juan, more on that below) developers are working
@ -50,8 +49,7 @@ positive to the engine, regardless of their skill set:
some money to the project, check `our website ( https://pandemoniumengine.org/donate )`
for details.
Contributing code
-----------------
## Contributing code
The possibility to study, use, modify and redistribute modifications of the
engine's source code are the fundamental rights that
@ -113,16 +111,14 @@ Note:
Proposals are only required when working on an enhancement or a new feature.
Bug reports are sufficient for fixing issues.
Testing and reporting issues
----------------------------
## Testing and reporting issues
Another great way of contributing to the engine is to test development releases
or the development branch and to report issues. It is also helpful to report
issues discovered in stable releases, so that they can be fixed in
the development branch and in future maintenance releases.
Testing development versions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
### Testing development versions
To help with the testing, you have several possibilities:
@ -142,8 +138,7 @@ potential bugs that might still be present in the stable releases, especially
when using some niche features of the engine which might get less testing by
the developers.
Filing an issue on GitHub
~~~~~~~~~~~~~~~~~~~~~~~~~
### Filing an issue on GitHub
Pandemonium uses `GitHub's issue tracker ( https://github.com/Relintai/pandemonium_engine/issues )`
for bug reports and enhancement suggestions. You will need a GitHub account to
@ -191,8 +186,7 @@ When you click the **New issue** button, you should be presented with a text are
prefilled with our issue template. Please try to follow it so that all issues
are consistent and provide the required information.
Contributing to the documentation
---------------------------------
## Contributing to the documentation
There are two separate resources referred to as "documentation" in Pandemonium:
@ -211,8 +205,7 @@ There are two separate resources referred to as "documentation" in Pandemonium:
`pandemonium-docs ( https://github.com/Relintai/pandemonium_engine-docs )` GitHub repository.
See `doc_contributing_to_the_documentation` for more details.
Contributing translations
-------------------------
## Contributing translations
To make Pandemonium accessible to everyone, including users who may prefer resources
in their native language instead of English, our community helps translate both

36
06_community/contributing/03_best_practices_for_engine_contributors.md
View File

@ -1,10 +1,8 @@
Best practices for engine contributors
======================================
# Best practices for engine contributors
Introduction
------------
## Introduction
Pandemonium has a large amount of users who have the ability to contribute, given the
project itself is aimed mainly at users with the ability to do programming.
@ -12,8 +10,7 @@ Despite this, not all of them have the same level of experience working in large
projects or in software engineering, which can lead to common misunderstandings
and bad practices during the process of contributing code to the project.
Language
--------
## Language
The scope of this document is to be a list of best practices for contributors to
follow, as well as to create a language they can use to refer to common
@ -27,11 +24,9 @@ Contributions are most of the time categorized as bug fixes, enhancements or new
features. To abstract this idea, we will call them *Solutions*, because they
always seek to solve something that can be described as a *Problem*.
Best Practices
--------------
## Best Practices
#1: The problem always comes first
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
### 1: The problem always comes first
Many contributors are extremely creative and just enjoy the process of designing
abstract data structures, creating nice user interfaces, or simply love
@ -46,8 +41,7 @@ as source and binary and requires maintenance once it exists. Avoiding the
addition of anything unnecessary is always considered a good practice in
software development.
#2: To solve the problem, it has to exist in the first place
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
### 2: To solve the problem, it has to exist in the first place
This is a variation of the previous practice. Adding anything unnecessary is not
a good idea, but what constitutes what is necessary and what isn't?
@ -72,8 +66,7 @@ This is generally considered a bad habit because trying to solve problems that
written but never used, or that is considerably more complex to use and maintain
than it needs to be.
#3: The problem has to be complex or frequent
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
### 3: The problem has to be complex or frequent
Software is designed to solve problems, but we can't expect it to solve *every
problem that exists under the sun*. As a game engine, Pandemonium will solve problems
@ -101,8 +94,7 @@ In our experience, in most cases it's usually obvious to tell when a problem is
complex or frequent, but cases may arise where drawing this line is difficult.
This is why discussing with other developers (next point) is always advised.
#4: The solution must be discussed with others
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
### 4: The solution must be discussed with others
It is often the case that when users stumble upon problems, they are only
immersed in their project, so they will naturally try to solve the problem
@ -133,8 +125,7 @@ performance. Performance optimizations will be considered, but they may not
be accepted if they make something too difficult to use or if they add too much
complexity to the codebase.
#5: To each problem, its own solution
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
### 5: To each problem, its own solution
For programmers, it is always a most enjoyable challenge to find the most
optimal solutions to problems. Things, however, may go overboard sometimes and
@ -160,8 +151,7 @@ Big and flexible solutions also have an additional drawback which is that, over
time, they are rarely flexible enough for all users, who keep requesting more
functions added (and making the API and codebase more and more complex).
#6: Cater to common use cases, leave the door open for the rare ones
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
### 6: Cater to common use cases, leave the door open for the rare ones
This is a continuation of the previous point, which further explains why this
way of thinking and designing software is preferred.
@ -191,8 +181,7 @@ In real-life scenarios, these use cases will be at most rare and uncommon
anyway, so it makes sense a custom solution needs to be written. This is why
it's important to still provide users the basic building blocks to do it.
#7: Prefer local solutions
~~~~~~~~~~~~~~~~~~~~~~~~~~
### 7: Prefer local solutions
When looking for a solution to a problem, be it implementing a new feature or
fixing a bug, sometimes the easiest path is to add data or a new function in the
@ -219,8 +208,7 @@ should be closer to where the problem originates, even if it involves more code,
duplicated, more complex or is less efficient. More creativity might be needed,
but this path is always the advised one.
#8: Don't use complex canned solutions for simple problems
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
### 8: Don't use complex canned solutions for simple problems
Not every problem has a simple solution and, many times, the right choice is to
use a third party library to solve the problem.

34
06_community/contributing/04_pr_workflow.md
View File

@ -1,8 +1,6 @@
Pull request workflow
=====================
# Pull request workflow
The so-called "PR workflow" used by Pandemonium is common to many projects using
Git, and should be familiar to veteran free software contributors. The idea
@ -22,8 +20,7 @@ We will go together through an example to show the typical workflow and
associated Git commands. But first, let's have a quick look at the
organization of Pandemonium's Git repository.
Git source repository
---------------------
## Git source repository
The `repository on GitHub ( https://github.com/Relintai/pandemonium_engine )` is a
`Git ( https://git-scm.com )` code repository together with an embedded
@ -69,8 +66,7 @@ The branches on the Git repository are organized as follows:
- There might occasionally be feature branches, usually meant to be merged into
the `master` branch at some time.
Forking and cloning
-------------------
## Forking and cloning
The first step is to *fork* the `pandemoniumengine/pandemonium ( https://github.com/Relintai/pandemonium_engine )`
repository on GitHub. To do so, you will need to have a GitHub account and to
@ -143,8 +139,7 @@ In the following, we will assume as an example that you want to implement a feat
Pandemonium's project manager, which is coded in the `editor/project_manager.cpp`
file.
Branching
---------
## Branching
By default, the `git clone` should have put you on the `master` branch of
your fork (`origin`). To start your own feature development, we will create
@ -189,8 +184,7 @@ you can specify a custom base branch after the new branch's name:
$ git checkout -b my-new-feature master
```
Updating your branch
--------------------
## Updating your branch
This would not be needed the first time (just after you forked the upstream
repository). However, the next time you want to work on something, you will
@ -254,8 +248,7 @@ Tip:
to find the commit ID of the previous state that you would like to restore, and
use it as argument of `git reset --hard` to go back to that state.
Making changes
--------------
## Making changes
You would then do your changes to our example's
`editor/project_manager.cpp` file with your usual development environment
@ -333,8 +326,7 @@ With this, we should have two new commits in our `better-project-manager`
branch which were not in the `master` branch. They are still only local
though, the remote fork does not know about them, nor does the upstream repo.
Pushing changes to a remote
---------------------------
## Pushing changes to a remote
That's where `git push` will come into play. In Git, a commit is always
done in the local repository (unlike Subversion where a commit will modify
@ -357,8 +349,7 @@ Git will ask you for your username and password, and the changes will be sent
to your remote. If you check the fork's page on GitHub, you should see a new
branch with your added commits.
Issuing a pull request
----------------------
## Issuing a pull request
When you load your fork's branch on GitHub, you should see a line saying
*"This branch is 2 commits ahead of pandemoniumengine:master."* (and potentially some
@ -379,8 +370,7 @@ area. You can drag and drop screenshots, GIFs or zipped projects if relevant,
to showcase what your work implements. Click "Create a pull request", and
tadaa!
Modifying a pull request
------------------------
## Modifying a pull request
While it is reviewed by other contributors, you will often need to make
changes to your yet-unmerged PR, either because contributors requested them,
@ -430,8 +420,7 @@ fixes. The above example would then become:
The interactive rebase
----------------------
## The interactive rebase
If you didn't follow the above steps closely to *amend* changes into a commit
instead of creating fixup commits, or if you authored your changes without being
@ -530,8 +519,7 @@ And tadaa! Git will happily *replace* your remote branch with what you had
locally (so make sure that's what you wanted, using `git log`). This will
also update the PR accordingly.
Deleting a Git branch
---------------------
## Deleting a Git branch
After your pull request gets merged, there's one last thing you should do: delete your
Git branch for the PR. There won't be issues if you don't delete your branch, but it's

16
06_community/contributing/05_testing_pull_requests.md
View File

@ -1,7 +1,6 @@
Testing pull requests
=====================
# Testing pull requests
Many people are developing new features or fixing bugs on GitHub.
To help with engine development, you may be asked to test those pull requests
@ -11,8 +10,7 @@ Thanks to GitHub Actions, all `pull requests ( https://github.com/Relintai/pande
have continuous builds available. These builds let you try out pull requests
without having to compile anything from source.
Downloading a compiled build
----------------------------
## Downloading a compiled build
You can download pull request builds from GitHub Actions. Since only signed in
users may download builds directly from GitHub Actions, the procedure varies
@ -27,8 +25,7 @@ Note:
`compile the pull request branch from source ( doc_testing_pull_requests_compile )`
instead.
If you have a GitHub account
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
#### If you have a GitHub account
- Open the pull request page. Click the **Checks** tab near the top of the page:
@ -51,8 +48,7 @@ If you have a GitHub account
If you frequently test pull request builds, it may be better to disable
Windows SmartScreen or `disable macOS Gatekeeper ( https://disable-gatekeeper.github.io/ )` permanently.
If you don't have a GitHub account
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
#### If you don't have a GitHub account
If you don't have a GitHub account and can't sign up for one,
you can use the third-party `nightly.link ( https://nightly.link )` service
@ -84,9 +80,7 @@ to generate a universal download link.
Windows SmartScreen or `disable macOS Gatekeeper ( https://disable-gatekeeper.github.io/ )` permanently.
Compiling a pull request branch from source
-------------------------------------------
## Compiling a pull request branch from source
This approach may be needed for pull requests that were last updated more than
90 days ago, or to test on platforms and configurations that are not supported

15
06_community/contributing/06_bisecting_regressions.md
View File

@ -1,7 +1,6 @@
Bisecting regressions
=====================
# Bisecting regressions
Bisecting is a way to find regressions in software. After reporting a bug on the
@ -12,8 +11,7 @@ the regression. Your effort will be widely appreciated :)
The guide below explains how to find a regression by bisecting.
What is bisecting?
------------------
## What is bisecting?
Pandemonium developers use the `Git ( https://git-scm.com/ )` version control system.
In the context of Git, bisecting is the process of performing a manual
@ -22,8 +20,7 @@ to determine when a regression appeared. While it's typically used for bugs,
it can also be used to find other kinds of unexpected changes such as
performance regressions.
Using official builds to speed up bisecting
-------------------------------------------
## Using official builds to speed up bisecting
Before using Git's `bisect` command, we strongly recommend trying to reproduce
the bug with an older (or newer) official release. This greatly reduces the
@ -40,15 +37,13 @@ manage to reproduce the bug with Pandemonium 3.2 beta 1, then try older alpha bu
Warning:
For bisecting regressions, don't use patch releases such as Pandemonium 3.1.2.
Instead, use the minor version's first release like Pandemonium 3.1. This is
because patch releases are built from a separate *stable branch*. This kind
of branch doesn't follow the rest of Pandemonium's development, which is done in
the `master` branch.
The Git bisect command
----------------------
## The Git bisect command
If you've found a build that didn't exhibit the bug in the above testing
process, you can now start bisecting the regression. The Git version control
@ -58,7 +53,6 @@ reproduce the bug.
Note:
Before bisecting a regression, you need to set up a build environment to
compile Pandemonium from source. To do so, read the
`Compiling ( toc-devel-compiling )` page for your target platform.
@ -142,6 +136,5 @@ contributing to Pandemonium :)
Note:
You can read the full documentation on `git bisect`
`here ( https://git-scm.com/docs/git-bisect )`.

15
06_community/contributing/07_bug_triage_guidelines.md
View File

@ -1,7 +1,6 @@
Bug triage guidelines
=====================
# Bug triage guidelines
This page describes the typical workflow of the bug triage team aka
bugsquad when handling issues and pull requests on Pandemonium's
@ -9,8 +8,7 @@ bugsquad when handling issues and pull requests on Pandemonium's
It is bound to evolve together with the bugsquad, so do not
hesitate to propose modifications to the following guidelines.
Issues management
-----------------
## Issues management
GitHub proposes various features to manage issues:
@ -31,8 +29,7 @@ For the time being, we do not use the project dashboard feature either.
As far as possible, we try to assign labels (and milestones, when relevant)
to both issues and pull requests.
Labels
~~~~~~
### Labels
The following labels are currently defined in the Pandemonium repository:
@ -146,8 +143,7 @@ If one of the platform labels is used, it is then exclusive and the
previous assumption doesn't stand anymore (so if it's a bug on e.g.
Android and Linux exclusively, select those two platforms).
Documentation labels
~~~~~~~~~~~~~~~~~~~~
### Documentation labels
In the `documentation repository ( https://github.com/Relintai/pandemonium_engine-docs )`, we
use the following labels:
@ -174,8 +170,7 @@ use the following labels:
- *Topic:Website*: the issue relates to the Sphinx/Read the Docs frontend or backend,
not the documentation contents.
Milestones
~~~~~~~~~~
### Milestones
`Milestones ( https://github.com/Relintai/pandemonium_engine/milestones )` correspond to
planned future versions of Pandemonium for which there is an existing roadmap. Issues

53
06_community/contributing/08_code_style_guidelines.md
View File

@ -1,8 +1,5 @@
Code style guidelines
=====================
# Code style guidelines
When contributing to Pandemonium's source code, you will be expected to follow the
style guidelines outlined below. Some of them are checked via the Continuous
@ -10,8 +7,7 @@ Integration process and reviewers will ask you to fix potential issues, so
best setup your system as outlined below to ensure all your commits follow the
guidelines.
C++ and Objective-C
-------------------
## C++ and Objective-C
There are no written guidelines, but the code style agreed upon by the
developers is enforced via the `clang-format ( http://clang.llvm.org/docs/ClangFormat.html )`
@ -34,6 +30,7 @@ fine. If you plan to contribute regularly however, we strongly advise that you
setup clang-format locally to check and automatically fix all your commits.
Warning:
Pandemonium's code style should *not* be applied to third-party code,
i.e. that is included in Pandemonium's source tree but was not written
specifically for our project. Such code usually come from
@ -50,20 +47,17 @@ Warning:
See also:
These guidelines only cover code formatting. See `doc_cpp_usage_guidelines`
for a list of language features that are permitted in pull requests.
Using clang-format locally
~~~~~~~~~~~~~~~~~~~~~~~~~~
### Using clang-format locally
First of all, you will need to install clang-format. As of now, you need to use
**clang-format 13** to be compatible with Pandemonium's format. Later versions might
be suitable, but previous versions may not support all used options, or format
some things differently, leading to style issues in pull requests.
Installation
^^^^^^^^^^^^
#### Installation
Here's how to install clang-format:
@ -79,8 +73,7 @@ Here's how to install clang-format:
You then have different possibilities to apply clang-format to your changes:
Manual usage
^^^^^^^^^^^^
#### Manual usage
You can apply clang-format manually one or more files with the following
command:
@ -96,8 +89,7 @@ command:
you don't run clang-format on compiled objects (.o and .a files) that are
in Pandemonium's tree. So better use `core/*.{cpp,h}` than `core/*`.
Pre-commit hook
^^^^^^^^^^^^^^^
#### Pre-commit hook
For ease of use, we provide a pre-commit hook for Git that will run
clang-format automatically on all your commits to check them, and let you apply
@ -111,8 +103,7 @@ If your clang-format is not in the `PATH`, you may have to edit the
The hook was tested on Linux and macOS, but should also work in the Git Shell
on Windows.
IDE plugin
^^^^^^^^^^
#### IDE plugin
Most IDEs or code editors have beautifier plugins that can be configured to run
clang-format automatically, for example each time you save a file.
@ -129,9 +120,7 @@ Here is a non-exhaustive list of beautifier plugins for some IDEs:
(Pull requests welcome to extend this list with tested plugins.)
Header includes
~~~~~~~~~~~~~~~
### Header includes
When adding new C++ or Objective-C files or including new headers in existing
ones, the following rules should be followed:
@ -246,16 +235,14 @@ Example:
#include <zstd.h>
```
Java
----
## Java
Pandemonium's Java code (mostly in `platform/android`) is also enforced via
`clang-format`, so see the instructions above to set it up. Keep in mind that
this style guide only applies to code written and maintained by Pandemonium, not
third-party code such as the `java/src/com/google` subfolder.
Python
------
## Python
Pandemonium's SCons buildsystem is written in Python, and various scripts included
in the source tree are also using Python.
@ -263,14 +250,12 @@ in the source tree are also using Python.
For those, we follow the `Black style guide ( https://github.com/psf/black#the-black-code-style )`.
Blacken your Python changes using `Black ( https://pypi.org/project/black/ )`.
Using black locally
~~~~~~~~~~~~~~~~~~~
### Using black locally
First of all, you will need to install black. Black requires Python 3.6.0+
to run.
Installation
^^^^^^^^^^^^
#### Installation
Here's how to install black:
@ -280,8 +265,7 @@ Here's how to install black:
You then have different possibilities to apply black to your changes:
Manual usage
^^^^^^^^^^^^
#### Manual usage
You can apply `black` manually to one or more files with the following
command:
@ -295,8 +279,7 @@ command:
- The path can point to several files, either one after the other or using
wildcards like in a typical Unix shell.
Pre-commit hook
^^^^^^^^^^^^^^^
#### Pre-commit hook
For ease of use, we provide a pre-commit hook for Git that will run
black automatically on all your commits to check them, and let you apply
@ -306,15 +289,13 @@ This "hook" is a script which can be found in `misc/hooks`. Refer to that
folder's `README.md` for installation instructions.
Editor integration
^^^^^^^^^^^^^^^^^^
#### Editor integration
Many IDEs or code editors have beautifier plugins that can be configured to run
black automatically, for example each time you save a file. For details you can
check `Black editor integration ( https://github.com/psf/black#editor-integration )`.
Comment style guide
-------------------
## Comment style guide
This comment style guide applies to all programming languages used within
Pandemonium's codebase.

24
06_community/contributing/09_cpp_usage_guidelines.md
View File

@ -1,10 +1,7 @@
# C++ usage guidelines
C++ usage guidelines
====================
Rationale
---------
## Rationale
Since Pandemonium 4.0, the C++ standard used throughout the codebase is a subset of
**C++17**. While modern C++ brings a lot of opportunities to write faster, more
@ -39,16 +36,14 @@ See also:
See `doc_code_style_guidelines` for formatting guidelines.
Disallowed features
-------------------
## Disallowed features
**Any feature not listed below is allowed.** Using features like `constexpr`
variables and `nullptr` is encouraged when possible. Still, try to keep your
use of modern C++ features conservative. Their use needs to serve a real
purpose, such as improving code readability or performance.
Standard Template Library
^^^^^^^^^^^^^^^^^^^^^^^^^
#### Standard Template Library
We don't allow using the `STL ( https://en.wikipedia.org/wiki/Standard_Template_Library )`
as Pandemonium provides its own data types (among other things).
@ -64,13 +59,11 @@ This means that pull requests should **not** use `std::string`,
Note:
Pandemonium also has a List datatype (which is a linked list). While List is already used
in the codebase, it typically performs worse than other datatypes like Vector
and Array. Therefore, List should be avoided in new code unless necessary.
`auto` keyword
^^^^^^^^^^^^^^^^
#### `auto` keyword
Please don't use the `auto` keyword for type inference. While it can avoid
repetition, it can also lead to confusing code:
@ -90,21 +83,18 @@ pull requests.
We chose to forbid `auto` instead of allowing it on a case-by-case basis to
avoid having to decide on difficult edge cases. Thank you for your understanding.
Lambdas
^^^^^^^
#### Lambdas
Lambdas should be used conservatively when they make code effectively faster or
simpler, and do not impede readability. Please ask before using lambdas in a
pull request.
`#pragma once` directive
^^^^^^^^^^^^^^^^^^^^^^^^^^
#### `#pragma once` directive
To follow the existing style, please use standard `#ifdef`-based include
guards instead of `#pragma once` in new files.
See also:
See `doc_code_style_guidelines_header_includes` for guidelines on sorting
includes in C++ and Objective-C files.

16
06_community/contributing/10_content_guidelines.md
View File

@ -1,7 +1,5 @@
Content guidelines
==================
# Content guidelines
This document is here to help us assess what we should include in the official
documentation. Below, you will find a couple of principles and recommendations
@ -15,15 +13,13 @@ We want to achieve two goals:
programming foundations. Instead, we should provide a reference for how
Pandemonium's features work.
Guidelines and principles
-------------------------
## Guidelines and principles
Below are the guidelines we should strive to follow. They are not hard rules,
though: exceptionally, a topic will require breaking one or more of these.
Still, we should strive to achieve the two goals listed above.
Writing complete and accessible documentation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
### Writing complete and accessible documentation
**A feature doesn't exist unless it is documented**. If a user can't find
information about a feature and how it works, it doesn't exist to them. We
@ -31,7 +27,6 @@ should ensure that we cover everything Pandemonium does.
Note:
When adding or updating an engine feature, the documentation team needs to
know about it. Contributors should open an issue on the `pandemonium-docs` repository
when their work gets merged and requires documentation.
@ -49,7 +44,6 @@ second title makes it clear what the purpose of signals is.
Note:
Long section titles lead to long entries in the side menu, which can make
navigation cumbersome. Try to keep headings five words long or less.
@ -58,8 +52,7 @@ link it to the corresponding documentation. For instance, a page about physics
may use signals, in which case we could note that the page that introduces
signals is a pre-requisite.
Limiting cognitive load
~~~~~~~~~~~~~~~~~~~~~~~
### Limiting cognitive load
Limit the cognitive load required to read the documentation. The simpler and
more explicit language we use, the more efficient it becomes for people to
@ -87,7 +80,6 @@ practice explaining the feature before writing about it.
Note:
Having programming foundations is a pre-requisite to use a complex engine
like Pandemonium. Talking about variables, functions, or classes is acceptable.
But we should favor plain language over specific terminology like

10
06_community/contributing/11_building_the_manual.md
View File

@ -1,7 +1,6 @@
Building the manual with Sphinx
===============================
# Building the manual with Sphinx
This page explains how to build a local copy of the Pandemonium manual using the
Sphinx docs engine. This allows you to have local HTML files and build the
@ -87,10 +86,11 @@ You can also specify a list of files to build, which can greatly speed up compil
.. code:: sh
```
sphinx-build -b html ./ _build classes/class_node.rst classes/class_resource.rst
```
Building with Sphinx and virtualenv
-----------------------------------
## Building with Sphinx and virtualenv
If you want your Sphinx installation scoped to the project, you can install
sphinx-build using virtualenv. To do so, run this command from this repository's
@ -98,8 +98,10 @@ root folder:
.. code:: sh
```
virtualenv --system-site-packages env/
. env/bin/activate
pip3 install -r requirements.txt
```
Then, run `make html` as shown above.

8
06_community/contributing/12_updating_the_class_reference.md
View File

@ -1,7 +1,5 @@
Contributing to the class reference
===================================
# Contributing to the class reference
The class reference is available online in the `classes ( toc-class-ref )`
@ -19,7 +17,6 @@ taking care of a given class.
See also:
You can find the writing guidelines for the class reference `here ( doc_class_reference_writing_guidelines )`.
For details on Git usage and the pull request workflow, please
@ -62,8 +59,7 @@ Warning:
scripts as described in
`doc_class_reference_writing_guidelines_editing_xml`.
Updating the documentation template
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
### Updating the documentation template
When you create a new class or modify the engine's API, you need to re-generate the XML files in `doc/classes/`.

Some files were not shown because too many files have changed in this diff Show More