Cleanups.

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

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 Previously, importing assets in Pandemonium 2.x required manual maintenance
of a separate directory with source assets. Without doing this, it was 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 However, the `Resource Loader( ResourceLoader )` cannot access
non imported files, only the `File` class can. 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 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) 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 possible. Simply select all of them together in the resources dock and the
exposed parameters will apply to all of them when reimporting. 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 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 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 button and every selected asset will be reimported with only those
parameters changed. parameters changed.
Automatic reimport ## Automatic reimport
------------------
When the MD5 checksum of the source asset changes, Pandemonium will perform an When the MD5 checksum of the source asset changes, Pandemonium will perform an
automatic reimport of it, applying the preset configured for that specific automatic reimport of it, applying the preset configured for that specific
asset. asset.
Files generated ## Files generated
-----------------
Importing will add an extra `<asset>.import` file, containing the import Importing will add an extra `<asset>.import` file, containing the import
configuration. Make sure to commit these to your version control system! 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 reimporting time when checking out on another computer, but it takes considerably
more space and transfer time. Pick your poison! 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. Some source assets can be imported as different types of resources.
For this, select the relevant type of resource desired and For this, select the relevant type of resource desired and
@ -93,8 +85,7 @@ press "Reimport":
![](img/asset_workflow2.png) ![](img/asset_workflow2.png)
Changing default import parameters ## Changing default import parameters
-----------------------------------
Different types of games might require different defaults. Different types of games might require different defaults.
Changing the defaults per project can be achieved by using the 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) ![](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 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. correct way to deal with resources.

View File

@ -1,10 +1,8 @@
Importing images # Importing images
================
Supported image formats ## Supported image formats
-----------------------
Pandemonium can import the following 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, If you've compiled the Pandemonium editor from source with specific modules disabled,
some formats may not be available. some formats may not be available.
Importing textures ## Importing textures
------------------
The default action in Pandemonium is to import images as textures. Textures are stored 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 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) ![](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 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. 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. 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. 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. - **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 Size on disk is reduced and video memory usage is also decreased considerably
@ -79,40 +73,26 @@ Compress Mode
raw float images). raw float images).
In this table, each of the four options are described together with their 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 | | | 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 | | 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 | ![](img/bad.png) Large | ![](img/regular.png) Small | ![](img/good.png) Very Small | ![](img/regular.png) Small |
| Size on Disk | |bad| Large | |regular| Small | |good| Very Small | |regular| 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 |
| Memory Usage | |bad| Large | |bad| Large | |bad| Large | |good| Small | | 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 |
| 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 |
+----------------+------------------------+-------------------------------+-------------------------+------------------------------------------------------+
.. |bad| image:: img/bad.png)
.. |good| image:: img/good.png) ### HDR Mode
.. |regular| image:: img/regular.png)
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 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. 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. 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 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 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: Note:
Pandemonium requires the normal map to use the X+, Y+ and Z+ coordinates, this is 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 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 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 popular engines) can be found
`here ( http://wiki.polycount.com/wiki/Normal_Map_Technical_Details )`. `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. 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". 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. 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. 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 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: (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). 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. 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. 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. 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 sRGB on one of the copies only. Use the copy with sRGB enabled in 3D, and
the copy with sRGB disabled in 2D. the copy with sRGB disabled in 2D.
Process ## Process
-------
Some special processes can be applied to images when imported as textures. 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 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. 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. 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. 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. 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. 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`. 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. 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.

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 Pandemonium provides three options to import your audio data: WAV, Ogg Vorbis
and MP3. and MP3.
@ -27,27 +25,21 @@ Each has different advantages.
Here is a comparative chart. Here is a comparative chart.
+-----------------------------+-------------------+
| Format | 1 second of audio | | Format | 1 second of audio |
+=============================+===================+ |-----------------------------|-------------------|
| WAV 24-bit, 96 kHz, stereo | 576 KB | | WAV 24-bit, 96 kHz, stereo | 576 KB |
+-----------------------------+-------------------+
| WAV 16-bit, 44 kHz, mono | 88 KB | | WAV 16-bit, 44 kHz, mono | 88 KB |
+-----------------------------+-------------------+
| WAV 16-bit, IMA-ADPCM, mono | 22 KB | | WAV 16-bit, IMA-ADPCM, mono | 22 KB |
+-----------------------------+-------------------+
| MP3 192 Kb/s, stereo | 24 KB | | MP3 192 Kb/s, stereo | 24 KB |
+-----------------------------+-------------------+
| Ogg Vorbis 128 Kb/s, stereo | 16 KB | | Ogg Vorbis 128 Kb/s, stereo | 16 KB |
+-----------------------------+-------------------+
| Ogg Vorbis 96 Kb/s, stereo | 12 KB | | Ogg Vorbis 96 Kb/s, stereo | 12 KB |
+-----------------------------+-------------------+
Consider using WAV for short and repetitive sound effects, and Ogg Vorbis Consider using WAV for short and repetitive sound effects, and Ogg Vorbis
for music, speech, and long sound effects. for music, speech, and long sound effects.
Best practices ## Best practices
--------------
Pandemonium has an `extensive bus system ( doc_audio_buses )` with built-in effects. 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, 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. 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 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 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 Importing as WAV with the **Trimming** option enabled solves
this. this.
Looping ### Looping
~~~~~~~
Pandemonium supports looping in the samples (tools such as Sound Forge or 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 Audition can add loop points to WAV files). This is useful for sound

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

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. 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 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. 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 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 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 plugins. They work well, although they are not always up-to date
with the latest version of the software. 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), 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). and with textures (`gltf` + `.bin` + textures).
@ -54,12 +50,10 @@ either of those glTF binary files are fine.
Warning: Warning:
Blend shape animations cannot be imported - they require manual animation within Pandemonium. Blend shape animations cannot be imported - they require manual animation within Pandemonium.
Note: Note:
Blender versions older than 3.2 do not export emissive textures with the 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 glTF file. If your model uses one and you're using an older version of
Blender, it must be brought in separately. Blender, it must be brought in separately.
@ -71,8 +65,7 @@ Note:
being culled by other faces. To resolve this, enable **Backface Culling** in being culled by other faces. To resolve this, enable **Backface Culling** in
Blender's Materials tab, then export the scene to glTF again. 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 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. 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 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. 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 The most powerful one, called `pandemonium-blender-exporter
( https://github.com/Relintai/pandemonium_engine-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 it keeps as much information as possible from a Blender scene. However, it is considered
experimental. 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. 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 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 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: Note:
For more information on Pandemonium's materials, see `doc_spatial_material`. 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 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 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 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. 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 Pandemonium scene importer allows different workflows regarding how data is imported. Depending on many options, it is possible to
import a scene with: import a scene with:
@ -140,33 +129,27 @@ import a scene with:
As different developers have different needs, this import process is highly customizable. 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: The importer has several options, which will be discussed below:
![](img/scene_import2.png) ![](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. 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. Allows setting a specific name to the generated root node.
Root Scale #### Root Scale
^^^^^^^^^^
The scale of the root node. The scale of the root node.
Custom Script #### Custom Script
^^^^^^^^^^^^^
A special script to process the whole scene after import can be provided. A special script to process the whole scene after import can be provided.
This is great for post processing, changing materials, doing funny stuff 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 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. 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 By default, Pandemonium imports a single scene. This option allows specifying
that nodes below the root will each be a separate scene and instanced 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. 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 Pandemonium supports materials in meshes or nodes. By default, materials will be put
on each node. on each node.
Storage #### Storage
^^^^^^^
Materials can be stored within the scene or in external files. By default, 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 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 dock, going to the Import dock then setting **Material > Storage** to
**Built-In** instead of **Files**. **Built-In** instead of **Files**.
Keep On Reimport #### Keep On Reimport
^^^^^^^^^^^^^^^^
Once materials are edited to use Pandemonium features, the importer will keep the 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 edited ones and ignore the ones coming from the source scene. This option
is only present if materials are saved as files. 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 Makes meshes use less precise numbers for multiple aspects of the mesh in order
to save space. 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) 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. 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. 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. This option ensures that these are generated if not present in the source scene.
Pandemonium uses `Mikktspace ( http://www.mikktspace.com/ )` for this, Pandemonium uses `Mikktspace ( http://www.mikktspace.com/ )` for this,
but it's always better to have them generated in the exporter. 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 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. 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 This option is provided to help those who prefer working directly with meshes
instead of scenes. instead of scenes.
Light Baking #### Light Baking
^^^^^^^^^^^^
Whether or not the mesh is used in baked lightmaps. 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: Note:
For more information on light baking see `doc_baked_lightmaps`. 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 Generated meshes and materials can be optionally stored in a subdirectory with the
name of the scene. name of the scene.
Animation options ## Animation options
-----------------
Pandemonium provides many options regarding how animation data is dealt with. Some exporters 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 (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. Import of animations is enabled by default.
.. attention:: Attention:
To modify animations from an imported 3D scene, you need to change the animation 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, 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. 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 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 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. 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 It is possible to specify a filter script in a special syntax to decide which tracks from which
animations should be kept. 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. 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 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. 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. 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. 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 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 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 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. 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. 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 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. 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: 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: Note:
All the suffixes described below are *case-sensitive*. 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 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. 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 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 static collision node will be added, using the same geometry as the mesh. This
@ -491,42 +451,35 @@ reliability.
Note: Note:
For better visibility in Blender's editor, you can set the "X-Ray" option 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 on collision empties and set some distinct color for them in Blender's
**User Preferences > Themes > 3D View > Empty**. **User Preferences > Themes > 3D View > Empty**.
See also: See also:
See `doc_collision_shapes_3d` for a comprehensive overview of collision See `doc_collision_shapes_3d` for a comprehensive overview of collision
shapes. shapes.
Create navigation (-navmesh) ### Create navigation (-navmesh)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A mesh node with the `-navmesh` suffix will be converted to a navigation mesh. A mesh node with the `-navmesh` suffix will be converted to a navigation mesh.
The original Mesh object will be removed at import-time. 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 A mesh node with the `-vehicle` suffix will be imported as a child to a
`VehicleBody` node. `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 A mesh node with the `-wheel` suffix will be imported as a child to a
`VehicleWheel` node. `VehicleWheel` node.
Rigid Body (-rigid) ### Rigid Body (-rigid)
~~~~~~~~~~~~~~~~~~~
A mesh node with the `-rigid` suffix will be imported as a `RigidBody`. 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` 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. will be imported as a Pandemonium Animation with the loop flag set.

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 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 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) ![](img/gltf_pandemonium_export.png)
Limitations ## Limitations
-----------
There are several limitations with glTF export. There are several limitations with glTF export.

View File

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

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 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 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 Where the exporter searches for the `.tres` file is determined by the "Material
Search Paths" option: Search Paths" option:
![](img/material_search.jpg ![](img/material_search.jpg)
This can take the value of: This can take the value of:
- Project Directory - Attempts to find the `project.Pandemonium` and recursively - 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. - 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 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 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. 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 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` the `escn` file. There is an option which could enable generating external `.material`
file when the `escn` file opens in Pandemonium. 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. `.material` file can be assigned to any material slot to be a external resource.
![](img/gd_dot_material.jpg ![](img/gd_dot_material.jpg)

View File

@ -1,33 +1,32 @@
Physics properties
================== # Physics properties
Exporting physics properties is done by enabling "Rigid Body" in Blender's Exporting physics properties is done by enabling "Rigid Body" in Blender's
physics tab: physics tab:
![](img/enable_physics.png) ![](img/enable_physics.png)
.. important:: Important:
By default, a single Blender object with rigid body enabled will export as By default, a single Blender object with rigid body enabled will export as
three nodes: a PhysicsBody, a CollisionShape, and a MeshInstance. 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 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 turn into Static and RigidBody nodes. To create a kinematic body, enable the
"animated" checkbox on an "Active" body: "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 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 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 options in Blender's rigid body collision and rigid body dynamics interfaces
are supported: are supported:
![](img/collision_shapes.jpg ![](img/collision_shapes.jpg)
There are the following caveats: There are the following caveats:
- Not all of the collision shapes are supported. Only `Mesh`, `Convex - 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 enabled. The physics properties are taken from the parent-most
rigid body, and the rest are used as collision shapes. 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 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 graphical meshes, but by default, the exporter will export a mesh along with the

View File

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

View File

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

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 Armature object in Blender is exported as a Skeleton node along with
rest position (transform in Pandemonium) of bones. 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 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. 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 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 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 deformed. Therefore, the exporter would raise an error for any vertex with no bone weights
detected in a rigged mesh. detected in a rigged mesh.
Non-Deform Bone ## Non-Deform Bone
---------------
Note that the non-deform bone can be configured as not exported Note that the non-deform bone can be configured as not exported
by enabling the :code:`Exclude Control Bones`; the deform bone by enabling the :code:`Exclude Control Bones`; the deform bone
checkbox is shown in the picture. 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 A bone can be the parent of an object in Blender; this relation is exported
as a BoneAttachment node in the Pandemonium scene. as a BoneAttachment node in the Pandemonium scene.

View File

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

View File

Before

Width:  |  Height:  |  Size: 40 KiB

After

Width:  |  Height:  |  Size: 40 KiB

View File

Before

Width:  |  Height:  |  Size: 12 KiB

After

Width:  |  Height:  |  Size: 12 KiB

View File

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

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 The engine offers two main ways to create reusable objects: scripts and scenes. Neither of these
technically define classes under the hood. 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 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 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 The engine provides built-in classes like `Node`. You can extend those to create
derived types using a script. derived types using a script.
@ -46,8 +43,7 @@ Note:
`extends` keyword from code. Since they extend `Reference` though, you cannot attach them to `extends` keyword from code. Since they extend `Reference` though, you cannot attach them to
a `Node`. a `Node`.
Scenes ## Scenes
------
The behavior of scenes has many similarities to classes, so it can make sense to think of a scene as 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 a class. Scenes are reusable, instantiable, and inheritable groups of nodes. Creating a scene is

View File

@ -1,14 +1,12 @@
Scene organization # Scene organization
==================
This article covers topics related to the effective organization of This article covers topics related to the effective organization of
scene content. Which nodes should one use? Where should one place them? scene content. Which nodes should one use? Where should one place them?
How should they interact? 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 When Pandemonium users begin crafting their own scenes, they often run into the
following problem: following problem:
@ -190,8 +188,7 @@ by *all* OOP principles. Examples include...
- `KISS ( https://en.wikipedia.org/wiki/KISS_principle )` - `KISS ( https://en.wikipedia.org/wiki/KISS_principle )`
- `YAGNI ( https://en.wikipedia.org/wiki/You_aren%27t_gonna_need_it )` - `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 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 before them. They might know what they want to do, what systems they want to

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 We've already covered how scenes and scripts are different. Scripts
define an engine class extension with imperative code, scenes with 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 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. 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. 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 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 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. 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 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 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. 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. 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 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. 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: In the end, the best approach is to consider the following:

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, 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: 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 In this guide, you will learn when to use the Autoload feature, and techniques
you can use to avoid it. 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 Other engines can encourage the use of creating manager classes, singletons that
organize a lot of functionality into a globally accessible object. Pandemonium offers 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. 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 Another reason to use an Autoload can be that you want to reuse the same method
or data across many scenes. 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 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. 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: Auto-loaded nodes can simplify your code in some cases:

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 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 have tens of thousands of nodes all doing things. The more complex their

View File

@ -1,7 +1,6 @@
Pandemonium interfaces # Pandemonium interfaces
================
Often one needs scripts that rely on other objects for features. There Often one needs scripts that rely on other objects for features. There
are 2 parts to this process: 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. 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 For all `Object`\s, the most basic way of referencing them
is to get a reference to an existing object from another acquired instance. is to get a reference to an existing object from another acquired instance.
@ -131,10 +129,7 @@ gdscript GDScript
print(globals.my_getter()) 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 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**. operation, Pandemonium doesn't validate that it supports the operation by **type**.

View File

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

View File

@ -1,7 +1,6 @@
Data preferences # Data preferences
================
Ever wondered whether one should approach problem X with data structure 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. 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' algorithm / data structure for the job is part of what makes programmers'
skills valuable. skills valuable.
Array vs. Dictionary vs. Object ## Array vs. Dictionary vs. Object
-------------------------------
Pandemonium stores all variables in the scripting API in the Pandemonium stores all variables in the scripting API in the
`Variant ( https://docs.pandemoniumengine.org/en/latest/development/cpp/variant_class.html )` `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 `Array` as well as
`Object` s. `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 contents in a contiguous section of memory, i.e. they are in a row adjacent
to each other. to each other.
@ -57,7 +55,7 @@ Note:
type, meaning that its records can only contain a particular type (denoted type, meaning that its records can only contain a particular type (denoted
by angled brackets). So, for example, a by angled brackets). So, for example, a
`PoolStringArray` would be something like `PoolStringArray` would be something like
a `Vector<String )`. a `Vector&lt;String&gt;`.
Contiguous memory stores imply the following operation performance: 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 though. Done by re-sorting the Array after every edit and writing an
ordered-aware search algorithm. 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 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 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 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, From here, one can then create their own structures with specific features,
limited only by their imagination. 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 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 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 strings. That way, a separate data structure to execute on the printing is
unnecessary. 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? Under what circumstances should one use each of Pandemonium's animation classes?
The answer may not be immediately clear to new Pandemonium users. The answer may not be immediately clear to new Pandemonium users.

View File

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

View File

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

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 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. 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) ![](img/version_control_menu.png)
Official Git plugin ## Official Git plugin
-------------------
Using Git from inside the editor is supported with an official plugin. Using Git from inside the editor is supported with an official plugin.
You can find the latest releases You can find the latest releases
@ -22,8 +19,7 @@ You can find the latest releases
plugin can be found plugin can be found
`here ( https://github.com/Relintai/pandemonium_engine-git-plugin/wiki )`. `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: 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 - `.mono/`: This folder stores automatically-generated Mono files. It only exists
in projects that use the Mono version of Pandemonium. 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`. 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. This can lead to files unnecessarily being marked as modified by Git due to their line endings being converted automatically.

View File

@ -1,8 +1,8 @@
# Things that are not documented nor indicated anywhere
From https://github.com/godotengine/godot-docs/issues/4377 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 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 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 You can drag and drop nodes (1 or more) from Scene Tree into Script Editor to insert their path

View File

@ -1,5 +1,7 @@
# Thread pool module # Thread pool module
Todo: was merged into core.
A c++ Pandemonium engine module, that will help you with threading. 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 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. 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 # ThreadPoolJob
Contains a job that can run on different threads. 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() MyJob job = MyJob.new()
ThreadPool.add_job(job) 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)

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 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 # Features and Usage
## TexturePacker ## TexturePacker

View File

@ -2,14 +2,6 @@
This is a c++ engine module for the Pandemonium engine, containing my mesh merging utilities. 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 # Optional Dependencies
[Mesh Data Resource](https://github.com/Relintai/mesh_data_resource): Support for merged meshes, even in gles2. [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 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. `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)

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/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. `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 ## MeshDataResource
The resource that holds mesh and collider data. 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: 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) ![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)

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 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 # Optional Dependencies
[Mesh Data Resource](https://github.com/Relintai/mesh_data_resource): Support for merged meshes, even in gles2.\ [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, 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. 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)

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 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 # Optional Dependencies
[Mesh Data Resource](https://github.com/Relintai/mesh_data_resource): Support for merged meshes, even in gles2.\ [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, 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. 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)

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. 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 ## Optional Dependencies
`https://github.com/Relintai/texture_packer`: You get access to [TerraLibraryMerger](#voxellibrarymerger) and [TerraLibraryMergerPCM](#voxellibrarymergerpcm). \ `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. 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. 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```

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. 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 ## Optional Dependencies
`https://github.com/Relintai/thread_pool`: Threaded chunk generation. Without this terraman is single threaded! \ `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. 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. 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```

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 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 ## Optional Dependencies
`https://github.com/Relintai/texture_packer`: You get access to [VoxelLibraryMerger](#voxellibrarymerger) and [VoxelLibraryMergerPCM](#voxellibrarymergerpcm). \ `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. 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. 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```

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. 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 ## Project setup tl;dr
### First ### First
@ -565,36 +553,3 @@ https://github.com/Relintai/broken_seals_roguelike
2d: 2d:
https://github.com/Relintai/broken_seals_2d.git 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```

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 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 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)

View File

@ -2,14 +2,6 @@
This is a c++ engine module for the Pandemonium engine, containing smaller utilities. 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 # TouchButton
A `Control` based button, that handles multitouch properly. A `Control` based button, that handles multitouch properly.
@ -49,30 +41,5 @@ func _ready():
I recommend putting this code into a singleton. 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)

View File

Before

Width:  |  Height:  |  Size: 226 B

After

Width:  |  Height:  |  Size: 226 B

View File

Before

Width:  |  Height:  |  Size: 461 B

After

Width:  |  Height:  |  Size: 461 B

View File

Before

Width:  |  Height:  |  Size: 1.3 KiB

After

Width:  |  Height:  |  Size: 1.3 KiB

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 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. benefits to using `TileMap` nodes to design your levels.
@ -17,8 +14,7 @@ the TileMap.
![](img/tileset_draw_atlas.png) ![](img/tileset_draw_atlas.png)
Project setup ## Project setup
-------------
This demo will use the following tiles taken from Kenney's "Abstract Platformer" 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 )` 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 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. 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 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 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. 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 Once you've configured your tilemap, it's time to add a
`TileSet`. A TileSet is a `TileSet`. A TileSet is a
@ -106,8 +100,7 @@ the node's lock button:
![](img/tile_lock.png) ![](img/tile_lock.png)
Collision shapes ## Collision shapes
----------------
If you're making a map that needs collisions - walls, floor, or other obstacles, 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 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. 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 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 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 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. 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 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 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 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. 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 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. 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" All "on" and "off" bits must be satisfied for a bitmask to match, but "ignore"
bits are ignored. bits are ignored.
2x2 ### 2x2
~~~
In 2x2 mode, each bitmask contains four bits, one for each corner. In 2x2 mode, each bitmask contains four bits, one for each corner.
@ -223,8 +212,7 @@ Key:
![](img/autotile_template_2x2.png) ![](img/autotile_template_2x2.png)
3x3 (minimal) ### 3x3 (minimal)
~~~~~~~~~~~~~
In 3x3 (minimal) mode, each bitmask contains 9 bits (4 corners, 4 edges, 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. 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: Note:
Right-click an image and choose **Save image as…** to save it. Right-click an image and choose **Save image as…** to save it.
**Template - Generic:** **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) ![](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) 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. 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 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 select tiles manually, by clicking "Disable Autotile" at the top of the tile
selection window. selection window.
Autotile binding ### Autotile binding
~~~~~~~~~~~~~~~~
By default, autotile only checks for adjacent cells filled using the same 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 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 declaration, and you may need to close and reload the scene for these changes
to take effect. to take effect.
Tips and tricks ## Tips and tricks
---------------
- If you're using a `Camera2D` to scroll your level, you - If you're using a `Camera2D` to scroll your level, you
may notice lines appearing between your tiles. To fix this, open Project may notice lines appearing between your tiles. To fix this, open Project

Binary file not shown.

After

Width:  |  Height:  |  Size: 226 B

Binary file not shown.

After

Width:  |  Height:  |  Size: 461 B

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.3 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 812 B

Binary file not shown.

After

Width:  |  Height:  |  Size: 769 B

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.8 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.1 KiB

View File

@ -66,7 +66,7 @@ To list the available target platforms, use `scons platform=list`:
windows windows
x11 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 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 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 cores will be used for the build. Or leave it using one core, so you
can use your computer for something else :) 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: 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: 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. manager.
``` ```
scons platform=<platform> tools=yes/no scons platform=&lt;platform&gt; tools=yes/no
``` ```
## Target ## Target
@ -150,7 +150,7 @@ Target controls optimization and debug flags. Each mode means:
checks to run. 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 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. - **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 This flag appends `.32` or `.64` suffixes to resulting binaries when
@ -207,7 +207,7 @@ See also:
## Cleaning generated files ## Cleaning generated files
Sometimes, you may encounter an error due to generated files being present. You 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. list of build options you've used to build Pandemonium previously.
Alternatively, you can use `git clean -fixd` which will clean build artifacts Alternatively, you can use `git clean -fixd` which will clean build artifacts

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 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. 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 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 implementation of the Python language (which SCons is written in). It is currently

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 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`. your project to UWP instead, read `doc_exporting_for_uwp`.
Requirements ## Requirements
------------
- SCons 3.0+ (see `doc_compiling_for_windows` for more details). - SCons 3.0+ (see `doc_compiling_for_windows` for more details).
- Visual Studio 2017 or later. See `doc_compiling_for_windows` about the - 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 For a general overview of SCons usage for Pandemonium, see
`doc_introduction_to_the_buildsystem`. `doc_introduction_to_the_buildsystem`.
Compiling ## Compiling
---------
You need to open a proper Visual Studio prompt for the target architecture 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 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 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. To export using the editor you need to properly build package the templates.
You need all three architectures with `debug` and `release` templates to 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" If you don't want to replace the templates, you can set the "Custom Package"
property in the export window. 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 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 and signing, you can deploy and launch them using Visual Studio. It might be

View File

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

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 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 source code, and give useful tips for extending/fixing the engine on the
C++ side. C++ side.
Architecture diagram ## Architecture diagram
--------------------
The following diagram describes the architecture used by Pandemonium, from the The following diagram describes the architecture used by Pandemonium, from the
core components down to the abstracted drivers, via the scene core components down to the abstracted drivers, via the scene
structure and the servers. 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, If you are writing or correcting bugs affecting Pandemonium Engine's editor,
remember that the binary will by default run the project manager first, remember that the binary will by default run the project manager first,

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 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, used in almost every file. This page is geared towards beginner contributors,
but it can also be useful for those writing custom C++ modules. but it can also be useful for those writing custom C++ modules.
Print text ## Print text
----------
``` ```
// Prints a message to standard output. // 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 If you need to add placeholders in your messages, use format strings as
described below. described below.
Format a string ## Format a string
---------------
The `vformat()` function returns a formatted `String`. It behaves The `vformat()` function returns a formatted `String`. It behaves
in a way similar to C's `sprintf()`: 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 In most cases, try to use `vformat()` instead of string concatenation as it
makes for more readable code. 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. 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)); print_line(rtos(123.45));
``` ```
Internationalize a string ## Internationalize a string
-------------------------
There are two types of internationalization in Pandemonium's codebase: 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 string will never match the translation as it will have the placeholder
already replaced when it's passed to TranslationServer. 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 Pandemonium provides macros for clamping a value with a lower bound (`MAX`), an
upper bound (`MIN`) or both (`CLAMP`): 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 This works with any type that can be compared to other values (like `int` and
`float`). `float`).
Microbenchmarking ## Microbenchmarking
-----------------
If you want to benchmark a piece of code but don't know how to use a profiler, If you want to benchmark a piece of code but don't know how to use a profiler,
use this snippet: use this snippet:
@ -138,14 +132,12 @@ declaration.
Note: Note:
You may have to `#include "core/os/os.h"` if it's not present already. 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 When opening a pull request, make sure to remove this snippet as well as the
include if it wasn't there previously. include if it wasn't there previously.
Get project/editor settings ## Get project/editor settings
---------------------------
There are four macros available for this: 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 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. 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. Pandemonium features many error macros to make error reporting more convenient.

View File

@ -1,7 +1,6 @@
Core types # Core types
==========
Pandemonium has a rich set of classes and templates that compose its core, Pandemonium has a rich set of classes and templates that compose its core,
and everything is built upon them. 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 This reference will try to list them in order for their better
understanding. understanding.
Definitions ## Definitions
-----------
Pandemonium uses the standard C99 datatypes, such as `uint8_t`, Pandemonium uses the standard C99 datatypes, such as `uint8_t`,
`uint32_t`, `int64_t`, etc. which are nowadays supported by every `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 desired. However, by default, this has not been forced and CharType maps
directly to wchar_t. directly to wchar_t.
References: ### References:
~~~~~~~~~~~
- `core/typedefs.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/typedefs.h )` - `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, PC is a wonderful architecture. Computers often have gigabytes of RAM,
terabytes of storage and gigahertz of CPU, and when an application needs 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 pool will be rearranged and compacted on demand. Depending on the need
of the game, the programmer can configure the dynamic memory pool size. 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 Pandemonium has many tools for tracking memory usage in a game, especially
during debug. Because of this, the regular C and C++ library calls 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 for small, dynamic memory operations, as read() and write() are too slow for a
large amount of accesses. large amount of accesses.
References: ### References:
~~~~~~~~~~~
- `core/os/memory.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/os/memory.h )` - `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 )` - `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: 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 - It supports multi-threading, by using atomic operations on the
reference counter. reference counter.
References: ### References:
~~~~~~~~~~~
- `core/vector.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/vector.h )` - `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/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/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 )` - `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 Pandemonium also provides a String class. This class has a huge amount of
features, full Unicode support in all the functions (like case features, full Unicode support in all the functions (like case
operations) and utf8 parsing/extracting, as well as helpers for operations) and utf8 parsing/extracting, as well as helpers for
conversion and visualization. conversion and visualization.
References: ### References:
~~~~~~~~~~~
- `core/ustring.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/ustring.h )` - `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 StringNames are like a String, but they are unique. Creating a
StringName from a string results in a unique internal pointer for all 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 Creation of a StringName (especially a new one) is slow, but comparison
is fast. is fast.
References: ### References:
~~~~~~~~~~~
- `core/string_name.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/string_name.h )` - `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 There are several linear math types available in the core/math
directory. directory.
References: ### References:
~~~~~~~~~~~
- `core/math ( https://github.com/Relintai/pandemonium_engine/tree/3.x/core/math )` - `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 This is a special datatype used for storing paths in a scene tree and
referencing them fast. referencing them fast.
References: ### References:
~~~~~~~~~~~
- `core/node_path.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/node_path.h )` - `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 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 them. RIDs are opaque, meaning that the data they reference can't be
accessed directly. RIDs are unique, even for different types of accessed directly. RIDs are unique, even for different types of
referenced data. referenced data.
References: ### References:
~~~~~~~~~~~
- `core/rid.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/rid.h )` - `core/rid.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/rid.h )`

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 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 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 much easier task, as it allows for highly dynamic constructs not common
of C++ with little effort. Become a friend of Variant today. 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 )` - `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 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 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. 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/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 )` - `core/array.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/array.h )`

View File

@ -1,16 +1,12 @@
# Object class
Object class
============
See also: See also:
This page describes the C++ implementation of objects in Pandemonium. This page describes the C++ implementation of objects in Pandemonium.
Looking for the Object class reference? `Have a look here.` 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 `Object` is the base class for almost everything. Most classes in Pandemonium
inherit directly or indirectly from it. Objects provide reflection and 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. 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 )` - `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 ClassDB is a static class that holds the entire list of registered
classes that inherit from Object, as well as dynamic bindings to all 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 documented as thoroughly, the `D_METHOD()` macro can safely be ignored and a
string passing the name can be passed for brevity. 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 )` - `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: 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); BIND_CONSTANT(MODE_SECOND);
``` ```
Properties (set/get) ## Properties (set/get)
--------------------
Objects export properties, properties are useful for the following: 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 An additional method of creating properties exists when more flexibility
is desired (i.e. adding or removing properties on context). 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 This is also a little less efficient since `p_property` must be
compared against the desired names in serial order. compared against the desired names in serial order.
Dynamic casting ## Dynamic casting
---------------
Pandemonium provides dynamic casting between Object-derived classes, for Pandemonium provides dynamic casting between Object-derived classes, for
example: 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 on platforms where a small binary size is ideal, such as HTML5 or
consoles (with low memory footprint). consoles (with low memory footprint).
Signals ## Signals
-------
Objects can have a set of signals defined (similar to Delegates in other Objects can have a set of signals defined (similar to Delegates in other
languages). Connecting to them is rather easy: 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")) ADD_SIGNAL(MethodInfo("been_killed"))
``` ```
Notifications ## Notifications
-------------
All objects in Pandemonium have a `notification` All objects in Pandemonium have a `notification`
method that allows it to respond to engine level callbacks that may relate to it. 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. More information can be found on the `doc_pandemonium_notifications` page.
References ## References
----------
`Reference` inherits from Object and holds a `Reference` inherits from Object and holds a
reference count. It is the base for reference counted object types. 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<> `myref` is reference counted. It will be freed when no more Ref<>
templates point to it. templates point to it.
References: ### References:
~~~~~~~~~~~
- `core/reference.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/reference.h )` - `core/reference.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/reference.h )`
Resources: ## Resources:
----------
`Resource` inherits from Reference, so all resources `Resource` inherits from Reference, so all resources
are reference counted. Resources can optionally contain a path, which 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. Resources without a path are fine too.
References: ### References:
~~~~~~~~~~~
- `core/resource.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/resource.h )` - `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: Resources can be loaded with the ResourceLoader API, like this:
@ -300,13 +282,11 @@ the same time.
- resourceinteractiveloader (TODO) - resourceinteractiveloader (TODO)
References: ### References:
~~~~~~~~~~~
- `core/io/resource_loader.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/io/resource_loader.h )` - `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: 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 be bundled with the saved resource and assigned sub-IDs, like
`res://someresource.res::1`. This also helps to cache them when loaded. `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 )` - `core/io/resource_saver.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/io/resource_saver.h )`

View File

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

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 Pandemonium allows extending the engine in a modular way. New modules can be
created and then enabled/disabled. This allows for adding new engine 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 created and combined. The SCons build system will take care of it
transparently. transparently.
What for? ## What for?
---------
While it's recommended that most of a game be written in scripting (as 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++ 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. - Porting an existing game.
- Write a whole, new game in C++ because you can't live without C++. - 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 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 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 `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" #include "summator.h"
void register_summator_types() { void register_summator_types() {
ClassDB::register_class<Summator>(); ClassDB::register_class&lt;Summator&gt;();
} }
void unregister_summator_types() { void unregister_summator_types() {
@ -225,8 +220,7 @@ Note:
as subclasses. This can be raised to 13 by including the header as subclasses. This can be raised to 13 by including the header
file `core/method_bind_ext.gen.inc`. file `core/method_bind_ext.gen.inc`.
Using the module ## Using the module
----------------
You can now use your newly created module from any script: 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 you plan to use, then specify the path to the custom
template in each export preset. Otherwise, you'll get errors when template in each export preset. Otherwise, you'll get errors when
running the project as the module isn't compiled in the export 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. for more information.
Compiling a module externally ## Compiling a module externally
-----------------------------
Compiling a module involves moving the module's sources directly under the Compiling a module involves moving the module's sources directly under the
engine's `modules/` directory. While this is the most straightforward way to 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 )`. `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: 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 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 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 to document your newly created module in order to make it easier for users to
@ -477,7 +468,7 @@ Tip:
``` ```
Untracked files: 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/MyClass2D.xml
doc/classes/MyClass4D.xml doc/classes/MyClass4D.xml
@ -488,8 +479,8 @@ Tip:
3. Now we can generate the documentation: 3. Now we can generate the documentation:
We can do this via running Pandemonium's doctool i.e. `pandemonium --doctool <path )`, 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 `<path )` in XML format. 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 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. 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: 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 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 folder, make sure you don't lose work by extracting older docs from an older engine build
on top of the newer ones. 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: 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 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, 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. 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" return "path/to/icons"
``` ```
Summing up ## Summing up
----------
Remember to: Remember to:

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, 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? custom modules, but what if you want to use a larger, external library?
@ -75,7 +73,8 @@ need to be created:
register_types.cpp register_types.cpp
``` ```
.. important:: Important:
These files must be in the top-level folder of your module (next to your 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. `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 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 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 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. 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 git submodule add https://github.com/festvox/speech_tools
``` ```
.. important:: Important:
Please note that Git submodules are not used in the Pandemonium repository. If 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 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 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 pandemonium/modules/tts/SCsub
``` ```
Using the module ## Using the module
----------------
You can now use your newly created module from any script: You can now use your newly created module from any script:

View File

@ -1,10 +1,8 @@
Custom Pandemonium servers # Custom Pandemonium servers
====================
Introduction ## Introduction
------------
Pandemonium implements multi-threading as servers. Servers are daemons which Pandemonium implements multi-threading as servers. Servers are daemons which
manage data, process it, and push the result. Servers implement the 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 This guide assumes the reader knows how to create C++ modules and Pandemonium
data types. If not, refer to `doc_custom_modules_in_c++`. 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 )` - `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 )` - `Singleton pattern ( https://en.wikipedia.org/wiki/Singleton_pattern )`
- `Mediator pattern ( https://en.wikipedia.org/wiki/Mediator_pattern )` - `Mediator pattern ( https://en.wikipedia.org/wiki/Mediator_pattern )`
What for? ## What for?
---------
- Adding artificial intelligence. - Adding artificial intelligence.
- Adding custom asynchronous threads. - Adding custom asynchronous threads.
@ -32,8 +28,7 @@ What for?
- Adding a custom VoIP protocol. - Adding a custom VoIP protocol.
- And more... - 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, At minimum, a server must have a static instance, a sleep timer, a thread loop,
an initialization state and a cleanup procedure. 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`. 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 RID_Owner maintains a list of RIDs. In practice, RIDs are similar to writing
object-oriented C code. object-oriented C code.
@ -312,14 +306,12 @@ object-oriented C code.
} }
``` ```
References ### References
~~~~~~~~~~~
- `RID( rid )` - `RID( rid )`
- `core/rid.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/rid.h )` - `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 Servers are allocated in `register_types.cpp`. The constructor sets the static
instance and `init()` creates the managed thread; `unregister_types.cpp` 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 )` - `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. 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 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 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 to execute the desired behavior. The queue will be flushed whenever either
`SceneTree::idle` or `SceneTree::iteration` is executed. `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 )` - `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: Here is the GDScript sample code:
@ -502,8 +490,7 @@ Here is the GDScript sample code:
print(HilbertHotel.get_bus_info(r_id)) 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. - 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. - Connecting signal example code is pretty hacky.

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. ResourceFormatLoader is a factory interface for loading file assets.
Resources are primary containers. When load is called on the same file 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 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++`. data types. If not, refer to this guide `doc_custom_modules_in_c++`.
References ### References
~~~~~~~~~~
- `ResourceLoader( resourceloader )` - `ResourceLoader( resourceloader )`
- `core/io/resource_loader.cpp ( https://github.com/Relintai/pandemonium_engine/blob/master/core/io/resource_loader.cpp )` - `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 - Adding new support for many file formats
- Audio formats - Audio formats
- Video formats - Video formats
- Machine learning models - Machine learning models
What not? ## What not?
---------
- Raster images - Raster images
ImageFormatLoader should be used to load 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 )` - `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`. 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 If you'd like to be able to edit and save a resource, you can implement a
`ResourceFormatSaver`: `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` Pandemonium may not have a proper substitute within its `doc_core_types`
or managed resources. Pandemonium needs a new registered data type to 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. Some libraries may not define certain common routines such as IO handling.
Therefore, Pandemonium call translations are required. Therefore, Pandemonium call translations are required.
@ -298,15 +287,13 @@ calls into `std::istream`.
}; };
``` ```
References ### References
~~~~~~~~~~
- `istream ( http://www.cplusplus.com/reference/istream/istream/ )` - `istream ( http://www.cplusplus.com/reference/istream/istream/ )`
- `streambuf ( http://www.cplusplus.com/reference/streambuf/streambuf/?kw=streambuf )` - `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 )` - `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` Pandemonium registers `ResourcesFormatLoader` with a `ResourceLoader`
handler. The handler selects the proper loader automatically 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 )` - `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 Save a file called `demo.json` with the following contents and place it in the
project's root folder: project's root folder:

View File

@ -1,10 +1,8 @@
Custom AudioStreams # Custom AudioStreams
===================
Introduction ## Introduction
------------
AudioStream is the base class of all audio emitting objects. AudioStream is the base class of all audio emitting objects.
AudioStreamPlayer binds onto an AudioStream to emit PCM data 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 This guide assumes the reader knows how to create C++ modules. If not, refer to this guide
`doc_custom_modules_in_c++`. `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 )` - `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 )` - `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). - Binding external libraries (like Wwise, FMOD, etc).
- Adding custom audio queues - Adding custom audio queues
- Adding support for more audio formats - Adding support for more audio formats
Create an AudioStream ## Create an AudioStream
---------------------
An AudioStream consists of three components: data container, stream name, An AudioStream consists of three components: data container, stream name,
and an AudioStreamPlayback friend class generator. Audio data can be 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 )` - `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. 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 Pandemonium's AudioServer currently uses 44100 Hz sample rate. When other sample rates are
needed such as 48000, either provide one or use AudioStreamPlaybackResampled. 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();
~AudioStreamPlaybackResampledMyTone(); ~AudioStreamPlaybackResampledMyTone();
}; };
```
``` ```
#include "mytone_audiostream_resampled.h" #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 )` - `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 )` - `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 )` - `scene/audio/audioplayer.cpp ( https://github.com/Relintai/pandemonium_engine/blob/master/scene/audio/audio_player.cpp )`

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. 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. 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 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. 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.

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 optimize Pandemonium's performance, you need to know what to optimize first.
To this end, profilers are useful tools. To this end, profilers are useful tools.
Note: Note:
There is a built-in GDScript profiler in the editor, but using C++ profiler 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 may be useful in cases where the GDScript profiler is not accurate enough
or is missing information due to bugs in the profiler. or is missing information due to bugs in the profiler.
Recommended profilers ## Recommended profilers
---------------------
- `VerySleepy ( http://www.codersnotes.com/sleepy/ )` (Windows only) - `VerySleepy ( http://www.codersnotes.com/sleepy/ )` (Windows only)
- `HotSpot ( https://github.com/KDAB/hotspot )` (Linux 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 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. 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 To get useful profiling information, it is **absolutely required** to use a Pandemonium
build that includes debugging symbols. Official binaries do not include debugging 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 after compiling the binaries. Otherwise, you will no longer get useful
profiling information when running a profiler. 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, 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. 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. This will exit Pandemonium just after it finished starting.
The `--quit` option works with `--editor`, `--project-manager` or 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 also:
See `doc_command_line_tutorial` for more command line arguments See `doc_command_line_tutorial` for more command line arguments
supported by Pandemonium. supported by Pandemonium.
Profiler-specific instructions ## Profiler-specific instructions
------------------------------
VerySleepy #### VerySleepy
^^^^^^^^^^
- Start the Pandemonium editor or your project first. - Start the Pandemonium editor or your project first.
If you start the project manager, make sure to edit or run a 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). - 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 You can filter by module by finding a line whose **Module** matches the Pandemonium
executable name, right-clicking that line then choosing 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: - Your results window should now look something like this:
![](img/cpp_profiler_verysleepy_results_filtered.png) ![](img/cpp_profiler_verysleepy_results_filtered.png)
HotSpot #### HotSpot
^^^^^^^
- Open HotSpot. Click **Record Data**: - Open HotSpot. Click **Record Data**:
@ -136,8 +127,7 @@ Note:
This process attachment-based workflow is similar to the one used by VerySleepy. 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: - Open Xcode. Select **Open Developer Tool** - **Instruments** from the **Xcode** app menu:
- Double-click on **Time Profiler** in the **Instruments** window: - Double-click on **Time Profiler** in the **Instruments** window:

View File

@ -1,28 +1,24 @@
Android Studio # Android Studio
==============
`Android Studio ( https://developer.android.com/studio )` is a free `Android Studio ( https://developer.android.com/studio )` is a free
`JetBrains ( https://www.jetbrains.com/ )` IDE for Android development. `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 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. 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 - From the Android Studio's welcome window select **Open an existing
Android Studio project**. Android Studio project**.
.. figure:: img/android_studio_setup_project_1.png) ![figure-w480](img/android_studio_setup_project_1.png)
:figclass: figure-w480
:align: center Android Studio's welcome window.
Android Studio's welcome window.
- Navigate to `<Pandemonium root directory>/platform/android/java` and select the `settings.gradle` file. - Navigate to `<Pandemonium root directory>/platform/android/java` and select the `settings.gradle` file.
- Android Studio will import and index the project. - 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 If you run into any issues, ask for help in one of
`Pandemonium's community channels ( https://pandemoniumengine.org/community )`. `Pandemonium's community channels ( https://pandemoniumengine.org/community )`.

View File

@ -1,13 +1,11 @@
CLion # CLion
=====
`CLion ( https://www.jetbrains.com/clion/ )` is a commercial `CLion ( https://www.jetbrains.com/clion/ )` is a commercial
`JetBrains ( https://www.jetbrains.com/ )` IDE for C++. `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 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, 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 is located there) and select it (but *not* the
`CMakeLists.txt` file itself), then click **OK**. `CMakeLists.txt` file itself), then click **OK**.
.. figure:: img/clion_1_open.png) ![](img/clion_1_open.png)
:align: center
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: - If this popup window appears, select **This Window** to open the project:
.. figure:: img/clion_2_this_window.png) ![](img/clion_2_this_window.png)
:align: center
- Choose **Tools > CMake > Change Project Root** from the top menu and select - Choose **Tools > CMake > Change Project Root** from the top menu and select
the Pandemonium root folder. the Pandemonium root folder.
.. figure:: img/clion_3_change_project_root.png) ![](img/clion_3_change_project_root.png)
:align: center
- You should be now be able to see all the project files. Autocomplete should - You should be now be able to see all the project files. Autocomplete should
work once the project has finished indexing. 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 If you run into any issues, ask for help in one of
`Pandemonium's community channels ( https://pandemoniumengine.org/community )`. `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. 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. 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...** - In CLion, go to **Run > Attach to Process...**
.. figure:: img/clion_4_select_attach_to_process.png) ![](img/clion_4_select_attach_to_process.png)
:align: center
- Find and Select pandemonium in the list (or type the binary name/Process ID) - Find and Select pandemonium in the list (or type the binary name/Process ID)
.. figure:: img/clion_5_select_pandemonium_process.png) ![](img/clion_5_select_pandemonium_process.png)
:align: center
You can now use the debugging tools from CLion. You can now use the debugging tools from CLion.
Note: Note:
If you run the binary without any arguments, you will only debug the project manager window. 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. Don't forget to add the `--path path/to/your/pandemonium/project` argument to debug a project.

View File

@ -1,129 +1,91 @@
Code::Blocks # Code::Blocks
============
`Code::Blocks ( https://codeblocks.org/ )` is a free, open source, cross platform IDE. `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...**. From Code::Blocks' main screen, click **Create a new project** or select **File > New > Project...**.
.. figure:: img/code_blocks_file_new_project.png) ![](img/code_blocks_file_new_project.png)
:figclass: figure-w480
:align: center
In the **New from template** window, from **Projects**, select **Empty project**, and click **Go**. In the **New from template** window, from **Projects**, select **Empty project**, and click **Go**.
.. figure:: img/code_blocks_new_empty_project.png) ![](img/code_blocks_new_empty_project.png)
:figclass: figure-w480
:align: center
Click Next, to pass the welcome to the new empty project wizard. Click Next, to pass the welcome to the new empty project wizard.
.. figure:: img/code_blocks_wizard_welcome.png) ![](img/code_blocks_wizard_welcome.png)
:figclass: figure-w480
:align: center
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`. 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. 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) ![](img/code_blocks_project_title_and_location.png)
:figclass: figure-w480
:align: center
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**. 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) ![](img/code_blocks_compiler_and_configuration.png)
:figclass: figure-w480
:align: center
Configuring the build ## Configuring the build
---------------------
The first step is to change the project properties. Right-click on the new project and select **Properties...**. 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) ![](img/code_blocks_open_properties.png)
:figclass: figure-w480
:align: center
Check the **This is a custom Makefile** property. Click OK to save the changes. Check the **This is a custom Makefile** property. Click OK to save the changes.
.. figure:: img/code_blocks_project_properties.png) ![](img/code_blocks_project_properties.png)
:figclass: figure-w480
:align: center
The next step is to change the build options. Right-click on the new project and select **Build Options...**. 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) ![](img/code_blocks_open_build_options.png)
:figclass: figure-w480
:align: center
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. 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. 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) ![](img/code_blocks_scons_minimum.png)
:figclass: figure-w480
:align: center
.. figure:: img/code_blocks_scons_clean.png) ![](img/code_blocks_scons_clean.png)
:figclass: figure-w480
:align: center
Windows example: Windows example:
.. figure:: img/code_blocks_scons_windows.png) !{}(img/code_blocks_scons_windows.png)
:figclass: figure-w480
:align: center
Code::Blocks should now be configured to build Pandemonium; so either select **Build > Build**, click the gear button, or press :kbd:`Ctrl + F9`. 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. 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. Deselect the **Auto-generate filename prefix** and **Auto-generate filename extension** options.
.. figure:: img/code_blocks_build_targets.png) ![](img/code_blocks_build_targets.png)
:figclass: figure-w480
:align: center
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`. 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. 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...**. 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) ![](img/code_blocks_add_files_recursively.png)
:figclass: figure-w480
:align: center
It should automatically select the project folder; so simply click **Open**. By default, all code files are included, so simply click **OK**. 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) ![](img/code_blocks_select_files.png)
:figclass: figure-w480
:align: center
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**. 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) ![](img/code_blocks_update_editor_settings.png)
:figclass: figure-w480
:align: center
Under **General Settings**, on the **Editor Settings** tab, under **Tab Options** check **Use TAB character**. Under **General Settings**, on the **Editor Settings** tab, under **Tab Options** check **Use TAB character**.
.. figure:: img/code_block_use_tab_character.png) ![](img/code_block_use_tab_character.png)
:figclass: figure-w480
:align: center
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 )`. 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 )`.

View File

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

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

View File

@ -1,15 +1,13 @@
Visual Studio # Visual Studio
=============
`Visual Studio Community ( https://visualstudio.microsoft.com )` is a Windows-only IDE `Visual Studio Community ( https://visualstudio.microsoft.com )` is a Windows-only IDE
by `Microsoft ( https://microsoft.com )` that's free for non-commercial use. by `Microsoft ( https://microsoft.com )` that's free for non-commercial use.
It has many useful features, such as memory view, performance view, source It has many useful features, such as memory view, performance view, source
control and more. 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 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. 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. - Use the **Build** top menu to build the project.
Warning: Warning:
Visual Studio must be configured with the C++ package. It can be selected Visual Studio must be configured with the C++ package. It can be selected
in the intaller: in the intaller:
.. figure:: img/vs_1_install_cpp_package.png) ![](img/vs_1_install_cpp_package.png)
:align: center
Debugging the project ## Debugging the project
---------------------
Visual Studio features a powerful debugger. This allows the user to examine Pandemonium's 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, 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** - To configure the launch options to use with the debugger use **Project > Properties**
from the top menu: from the top menu:
.. figure:: img/vs_2_project_properties.png) ![](img/vs_2_project_properties.png)
:align: center
- Open the **Debugging** section and under **Command Arguments** add two new arguments: - 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 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 tells the executable to open the specified project (must be provided as an *absolute* path
to the project root, not the `project.pandemonium` file). to the project root, not the `project.pandemonium` file).
.. figure:: img/vs_3_debug_command_line.png) ![](img/vs_3_debug_command_line.png)
:align: center
To learn more about command line arguments, refer to the To learn more about command line arguments, refer to the
`command line tutorial ( doc_command_line_tutorial )`. `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 To check that everything is working, put a breakpoint in `main.cpp` and press :kbd:`F5` to
start debugging. start debugging.
.. figure:: img/vs_4_debugging_main.png) ![](img/vs_4_debugging_main.png)
:align: center
If you run into any issues, ask for help in one of If you run into any issues, ask for help in one of
`Pandemonium's community channels ( https://pandemoniumengine.org/community )`. `Pandemonium's community channels ( https://pandemoniumengine.org/community )`.

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 `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`). 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 - Make sure the C/C++ extension is installed. You can find instructions in
the `official documentation ( https://code.visualstudio.com/docs/languages/cpp )`. the `official documentation ( https://code.visualstudio.com/docs/languages/cpp )`.
@ -18,18 +16,15 @@ Importing the project
**File > Open Folder...**. **File > Open Folder...**.
- Press :kbd:`Ctrl + Shift + P` to open the command prompt window and enter *Configure Task*. - Press :kbd:`Ctrl + Shift + P` to open the command prompt window and enter *Configure Task*.
.. figure:: img/vscode_configure_task.png) ![](img/vscode_configure_task.png)
:align: center
- Select the **Create tasks.json file from template** option. - Select the **Create tasks.json file from template** option.
.. figure:: img/vscode_create_tasksjson.png) ![](img/vscode_create_tasksjson.png)
:align: center
- Then select **Others**. - Then select **Others**.
.. figure:: img/vscode_create_tasksjson_others.png) ![](img/vscode_create_tasksjson_others.png)
:align: center
- Within the `tasks.json` file find the `"tasks"` array and add a new section to it: - 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) ![](img/vscode_3_tasks.json.png)
:figclass: figure-w480
:align: center
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 Arguments can be different based on your own setup and needs. See
`doc_introduction_to_the_buildsystem` for a full list of arguments. `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. 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. - 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. - If `launch.json` file is missing you will be prompted to create a new one.
.. figure:: img/vscode_1_create_launch.json.png) ![](img/vscode_1_create_launch.json.png)
:align: center
- Select **C++ (GDB/LLDB)**. There may be another platform specific option here. If selected, - Select **C++ (GDB/LLDB)**. There may be another platform specific option here. If selected,
adjust the configuration example provided accordingly. adjust the configuration example provided accordingly.
@ -159,9 +150,7 @@ js Windows
} }
``` ```
.. figure:: img/vscode_2_launch.json.png) ![](img/vscode_2_launch.json.png)
:figclass: figure-w480
:align: center
An example of a filled out `launch.json`. An example of a filled out `launch.json`.

View File

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

View File

@ -1,7 +1,5 @@
# Introduction to editor development
Introduction to editor development
==================================
On this page, you will learn: On this page, you will learn:
@ -13,25 +11,22 @@ To create editor plugins in GDScript, see `doc_making_plugins` instead.
See also: See also:
If you are new to Pandemonium, we recommended you to read If you are new to Pandemonium, we recommended you to read
`doc_pandemonium_design_philosophy` before continuing. Since the Pandemonium editor `doc_pandemonium_design_philosophy` before continuing. Since the Pandemonium editor
is a Pandemonium project written in C++, much of the engine's philosophy applies is a Pandemonium project written in C++, much of the engine's philosophy applies
to the editor. to the editor.
Technical choices ## Technical choices
-----------------
The Pandemonium editor is drawn using Pandemonium's renderer and 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. 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 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. 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. 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 The editor's code is fully self-contained in the
`editor/ ( https://github.com/Relintai/pandemonium_engine/tree/master/editor )` folder `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. 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. 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 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. 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 files, but
`they are in the process of being removed ( https://github.com/Relintai/pandemonium_engine/issues/29730 )`. `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 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 `open it from the command line ( doc_command_line_tutorial )` after compiling

View File

@ -1,15 +1,13 @@
Editor icons # Editor icons
============
When a new class is created and exposed to scripting, the editor's interface 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 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 from. In most cases, it's still recommended to create icons for new classes to
improve the user experience. improve the user experience.
Creating icons ### Creating icons
~~~~~~~~~~~~~~
To create new icons, you first need a vector graphics editor installed. 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. 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 name in a case-sensitive manner. For example, to create an icon for
CPUParticles2D, name the file `CPUParticles2D.svg`. 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 If the user has configured their editor to use a light theme, Pandemonium will
convert the icon's colors based on a 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. 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. 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 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 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 recommended to keep the source SVG around if you need to make further
changes. 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 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 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 For specific instructions on how to create module icons, refer to
`Creating custom module icons( doc_custom_module_icons )`. `Creating custom module icons( doc_custom_module_icons )`.
Troubleshooting ### Troubleshooting
~~~~~~~~~~~~~~~
If icons don't appear in the editor, make sure that: 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, 2. `modules/svg` is enabled (it should be enabled by default). Without it,
icons won't appear in the editor at all. icons won't appear in the editor at all.
References ### References
~~~~~~~~~~
- `editor/icons ( https://github.com/Relintai/pandemonium_engine/tree/master/editor/icons )` - `editor/icons ( https://github.com/Relintai/pandemonium_engine/tree/master/editor/icons )`

View File

@ -1,10 +1,8 @@
Editor style guide # Editor style guide
==================
Introduction ## Introduction
------------
Thanks for your interest in contributing to the Pandemonium editor! 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 editor. Following this style guide will help your contribution get merged faster
since there will be fewer review steps required. since there will be fewer review steps required.
Writing style ## Writing style
-------------
- **Write messages (errors, warnings, ...) as full sentences.** They should start - **Write messages (errors, warnings, ...) as full sentences.** They should start
with an uppercase letter and end with a period. 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 Try to follow the `doc_docs_writing_guidelines` in addition to the
guidelines outlined above. guidelines outlined above.
Button and menu texts ## Button and menu texts
---------------------
Capitalize text in buttons and menu actions: 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...* - **Good:** *Editor Settings...*
- **Bad:** *Editor Settings* - **Bad:** *Editor Settings*
Inspector sections ## Inspector sections
------------------
In general, don't create sections that contain less than 3 items. Sections that 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 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. 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 Enum properties that noticeably impact performance should have a performance
hint associated. The hint should refer to the *absolute* performance impact, 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 If you're adding a new enum, its values should be ordered from the fastest
option to the slowest option. option to the slowest option.
Tooltips ## Tooltips
--------
Consider adding tooltips whenever the action performed by a button or menu Consider adding tooltips whenever the action performed by a button or menu
action isn't obvious. You can also provide additional context or highlight action isn't obvious. You can also provide additional context or highlight

View File

@ -1,7 +1,6 @@
TSCN file format # TSCN file format
================
The TSCN (text scene) file format represents a single scene tree inside 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 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 )` `resource_format_text.cpp ( https://github.com/Relintai/pandemonium_engine/blob/master/scene/resources/resource_format_text.cpp )`
in the `ResourceFormatLoaderText` class. in the `ResourceFormatLoaderText` class.
File structure ## File structure
--------------
There are five main sections inside the TSCN file: 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 (`;`). 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. 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 A heading looks like
`[<resource_type> key=value key=value key=value ...]` `[<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 ) 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 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 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 far = 100.0
``` ```
NodePath ### NodePath
~~~~~~~~
A tree structure is not enough to represent the whole scene. Pandemonium uses a 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 `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 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 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 = [ ] bones/1/bound_children = [ ]
``` ```
BoneAttachment ### BoneAttachment
~~~~~~~~~~~~~~
BoneAttachment node is an intermediate node to describe some node being parented BoneAttachment node is an intermediate node to describe some node being parented
to a single bone in a Skeleton node. The BoneAttachment has a 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) 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 AnimationPlayer works as an animation library. It stores animations listed in
the format `anim/Name=SubResource(ResourceId)`; each line refers to an the format `anim/Name=SubResource(ResourceId)`; each line refers to an
@ -251,8 +243,7 @@ AnimationPlayer. The root node is stored as
blend_times = [ ] blend_times = [ ]
``` ```
Resources ## Resources
---------
Resources are components that make up the nodes. For example, a MeshInstance Resources are components that make up the nodes. For example, a MeshInstance
node will have an accompanying ArrayMesh resource. The ArrayMesh resource 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" For example, to refer to the resource `[ext_resource id=3 type="PackedScene"
path=....]`, you would use `ExtResource(3)`. path=....]`, you would use `ExtResource(3)`.
External resources ### External resources
~~~~~~~~~~~~~~~~~~
External resources are links to resources not contained within the TSCN file 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. 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 semicolon (`;`). However, comments will be discarded when saving the resource
using the Pandemonium editor. using the Pandemonium editor.
Internal resources ### Internal resources
~~~~~~~~~~~~~~~~~~
A TSCN file can contain meshes, materials and other data. These are contained in 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 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 complete. Some examples can be found by inspecting saved resource files, but
others can only be found by looking through Pandemonium's source. others can only be found by looking through Pandemonium's source.
ArrayMesh ### ArrayMesh
~~~~~~~~~
ArrayMesh consists of several surfaces, each in the format `surface\Index={}`. ArrayMesh consists of several surfaces, each in the format `surface\Index={}`.
Each surface is a set of vertices and a material. 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` An animation resource consists of tracks. Besides, it has `length`, `loop`
and `step` applied to all the tracks. and `step` applied to all the tracks.

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/ )`. 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. 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. 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. 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). - `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). - `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). - `Garbaj ( https://www.youtube.com/c/Garbaj/ )` (3D, GDScript).
- `Kasper Frandsen ( https://www.youtube.com/c/KasperFrandsen/ )` (3D, Shaders). - `Kasper Frandsen ( https://www.youtube.com/c/KasperFrandsen/ )` (3D, Shaders).
Text tutorials ## Text tutorials
--------------
- `FinepointCGI website by Mitch ( http://finepointcgi.io/ )` - `FinepointCGI website by Mitch ( http://finepointcgi.io/ )`
- `GDScript website by Andrew Wilkes ( https://gdscript.com )` - `GDScript website by Andrew Wilkes ( https://gdscript.com )`
- `Pandemonium Recipes by KidsCanCode ( http://pandemoniumrecipes.com/ )` - `Pandemonium Recipes by KidsCanCode ( http://pandemoniumrecipes.com/ )`
- `Steincodes ( https://steincodes.tumblr.com )` - `Steincodes ( https://steincodes.tumblr.com )`
Devlogs ## Devlogs
-------
- `Andrea Catania (Physics & AI) ( https://www.youtube.com/channel/UCm4RuvYtgpgFDTCgaEUT5uQ/videos )` - `Andrea Catania (Physics & AI) ( https://www.youtube.com/channel/UCm4RuvYtgpgFDTCgaEUT5uQ/videos )`
- `Bastiaan Olij (AR & VR) ( https://www.youtube.com/channel/UCrbLJYzJjDf2p-vJC011lYw/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 )` - `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 )` - `Zeef Pandemonium Engine: A curated directory of resources by Andre Schmitz ( https://pandemonium-engine.zeef.com/andre.antonio.schmitz )`

View File

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

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. 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 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 )` some money to the project, check `our website ( https://pandemoniumengine.org/donate )`
for details. for details.
Contributing code ## Contributing code
-----------------
The possibility to study, use, modify and redistribute modifications of the The possibility to study, use, modify and redistribute modifications of the
engine's source code are the fundamental rights that 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. Proposals are only required when working on an enhancement or a new feature.
Bug reports are sufficient for fixing issues. 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 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 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 issues discovered in stable releases, so that they can be fixed in
the development branch and in future maintenance releases. the development branch and in future maintenance releases.
Testing development versions ### Testing development versions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To help with the testing, you have several possibilities: 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 when using some niche features of the engine which might get less testing by
the developers. 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 )` 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 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 prefilled with our issue template. Please try to follow it so that all issues
are consistent and provide the required information. 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: 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. `pandemonium-docs ( https://github.com/Relintai/pandemonium_engine-docs )` GitHub repository.
See `doc_contributing_to_the_documentation` for more details. 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 To make Pandemonium accessible to everyone, including users who may prefer resources
in their native language instead of English, our community helps translate both in their native language instead of English, our community helps translate both

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 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. 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 projects or in software engineering, which can lead to common misunderstandings
and bad practices during the process of contributing code to the project. 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 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 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 features. To abstract this idea, we will call them *Solutions*, because they
always seek to solve something that can be described as a *Problem*. 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 Many contributors are extremely creative and just enjoy the process of designing
abstract data structures, creating nice user interfaces, or simply love 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 addition of anything unnecessary is always considered a good practice in
software development. 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 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? 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 written but never used, or that is considerably more complex to use and maintain
than it needs to be. 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 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 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. 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. 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 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 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 be accepted if they make something too difficult to use or if they add too much
complexity to the codebase. 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 For programmers, it is always a most enjoyable challenge to find the most
optimal solutions to problems. Things, however, may go overboard sometimes and 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 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). 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 This is a continuation of the previous point, which further explains why this
way of thinking and designing software is preferred. 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 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. 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 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 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, duplicated, more complex or is less efficient. More creativity might be needed,
but this path is always the advised one. 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 Not every problem has a simple solution and, many times, the right choice is to
use a third party library to solve the problem. use a third party library to solve the problem.

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 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 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 associated Git commands. But first, let's have a quick look at the
organization of Pandemonium's Git repository. organization of Pandemonium's Git repository.
Git source repository ## Git source repository
---------------------
The `repository on GitHub ( https://github.com/Relintai/pandemonium_engine )` is a The `repository on GitHub ( https://github.com/Relintai/pandemonium_engine )` is a
`Git ( https://git-scm.com )` code repository together with an embedded `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 - There might occasionally be feature branches, usually meant to be merged into
the `master` branch at some time. 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 )` 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 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` Pandemonium's project manager, which is coded in the `editor/project_manager.cpp`
file. file.
Branching ## Branching
---------
By default, the `git clone` should have put you on the `master` branch of 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 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 $ 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 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 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 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. 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 You would then do your changes to our example's
`editor/project_manager.cpp` file with your usual development environment `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 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. 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 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 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 to your remote. If you check the fork's page on GitHub, you should see a new
branch with your added commits. 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 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 *"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 to showcase what your work implements. Click "Create a pull request", and
tadaa! tadaa!
Modifying a pull request ## Modifying a pull request
------------------------
While it is reviewed by other contributors, you will often need to make While it is reviewed by other contributors, you will often need to make
changes to your yet-unmerged PR, either because contributors requested them, 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 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 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 locally (so make sure that's what you wanted, using `git log`). This will
also update the PR accordingly. 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 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 Git branch for the PR. There won't be issues if you don't delete your branch, but it's

View File

@ -1,7 +1,6 @@
Testing pull requests # Testing pull requests
=====================
Many people are developing new features or fixing bugs on GitHub. 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 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 have continuous builds available. These builds let you try out pull requests
without having to compile anything from source. 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 You can download pull request builds from GitHub Actions. Since only signed in
users may download builds directly from GitHub Actions, the procedure varies 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 )` `compile the pull request branch from source ( doc_testing_pull_requests_compile )`
instead. 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: - 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 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. 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, 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 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. 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 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 90 days ago, or to test on platforms and configurations that are not supported

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 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. 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. 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 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 it can also be used to find other kinds of unexpected changes such as
performance regressions. 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 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 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: Warning:
For bisecting regressions, don't use patch releases such as Pandemonium 3.1.2. 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 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 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 of branch doesn't follow the rest of Pandemonium's development, which is done in
the `master` branch. 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 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 process, you can now start bisecting the regression. The Git version control
@ -58,7 +53,6 @@ reproduce the bug.
Note: Note:
Before bisecting a regression, you need to set up a build environment to Before bisecting a regression, you need to set up a build environment to
compile Pandemonium from source. To do so, read the compile Pandemonium from source. To do so, read the
`Compiling ( toc-devel-compiling )` page for your target platform. `Compiling ( toc-devel-compiling )` page for your target platform.
@ -142,6 +136,5 @@ contributing to Pandemonium :)
Note: Note:
You can read the full documentation on `git bisect` You can read the full documentation on `git bisect`
`here ( https://git-scm.com/docs/git-bisect )`. `here ( https://git-scm.com/docs/git-bisect )`.

View File

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

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 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 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 best setup your system as outlined below to ensure all your commits follow the
guidelines. guidelines.
C++ and Objective-C ## C++ and Objective-C
-------------------
There are no written guidelines, but the code style agreed upon by the 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 )` 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. setup clang-format locally to check and automatically fix all your commits.
Warning: Warning:
Pandemonium's code style should *not* be applied to third-party code, 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 i.e. that is included in Pandemonium's source tree but was not written
specifically for our project. Such code usually come from specifically for our project. Such code usually come from
@ -50,20 +47,17 @@ Warning:
See also: See also:
These guidelines only cover code formatting. See `doc_cpp_usage_guidelines` These guidelines only cover code formatting. See `doc_cpp_usage_guidelines`
for a list of language features that are permitted in pull requests. 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 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 **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 be suitable, but previous versions may not support all used options, or format
some things differently, leading to style issues in pull requests. some things differently, leading to style issues in pull requests.
Installation #### Installation
^^^^^^^^^^^^
Here's how to install clang-format: 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: 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 You can apply clang-format manually one or more files with the following
command: command:
@ -96,8 +89,7 @@ command:
you don't run clang-format on compiled objects (.o and .a files) that are 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/*`. 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 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 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 The hook was tested on Linux and macOS, but should also work in the Git Shell
on Windows. on Windows.
IDE plugin #### IDE plugin
^^^^^^^^^^
Most IDEs or code editors have beautifier plugins that can be configured to run 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. 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.) (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 When adding new C++ or Objective-C files or including new headers in existing
ones, the following rules should be followed: ones, the following rules should be followed:
@ -246,16 +235,14 @@ Example:
#include <zstd.h> #include <zstd.h>
``` ```
Java ## Java
----
Pandemonium's Java code (mostly in `platform/android`) is also enforced via 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 `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 this style guide only applies to code written and maintained by Pandemonium, not
third-party code such as the `java/src/com/google` subfolder. 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 Pandemonium's SCons buildsystem is written in Python, and various scripts included
in the source tree are also using Python. 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 )`. 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/ )`. 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+ First of all, you will need to install black. Black requires Python 3.6.0+
to run. to run.
Installation #### Installation
^^^^^^^^^^^^
Here's how to install black: 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: 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 You can apply `black` manually to one or more files with the following
command: command:
@ -295,8 +279,7 @@ command:
- The path can point to several files, either one after the other or using - The path can point to several files, either one after the other or using
wildcards like in a typical Unix shell. 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 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 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. 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 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 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 )`. 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 This comment style guide applies to all programming languages used within
Pandemonium's codebase. Pandemonium's codebase.

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 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 **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. See `doc_code_style_guidelines` for formatting guidelines.
Disallowed features ## Disallowed features
-------------------
**Any feature not listed below is allowed.** Using features like `constexpr` **Any feature not listed below is allowed.** Using features like `constexpr`
variables and `nullptr` is encouraged when possible. Still, try to keep your 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 use of modern C++ features conservative. Their use needs to serve a real
purpose, such as improving code readability or performance. 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 )` 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). 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: Note:
Pandemonium also has a List datatype (which is a linked list). While List is already used 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 in the codebase, it typically performs worse than other datatypes like Vector
and Array. Therefore, List should be avoided in new code unless necessary. 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 Please don't use the `auto` keyword for type inference. While it can avoid
repetition, it can also lead to confusing code: 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 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. 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 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 simpler, and do not impede readability. Please ask before using lambdas in a
pull request. pull request.
`#pragma once` directive #### `#pragma once` directive
^^^^^^^^^^^^^^^^^^^^^^^^^^
To follow the existing style, please use standard `#ifdef`-based include To follow the existing style, please use standard `#ifdef`-based include
guards instead of `#pragma once` in new files. guards instead of `#pragma once` in new files.
See also: See also:
See `doc_code_style_guidelines_header_includes` for guidelines on sorting See `doc_code_style_guidelines_header_includes` for guidelines on sorting
includes in C++ and Objective-C files. includes in C++ and Objective-C files.

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 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 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 programming foundations. Instead, we should provide a reference for how
Pandemonium's features work. Pandemonium's features work.
Guidelines and principles ## Guidelines and principles
-------------------------
Below are the guidelines we should strive to follow. They are not hard rules, 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. though: exceptionally, a topic will require breaking one or more of these.
Still, we should strive to achieve the two goals listed above. 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 **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 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: Note:
When adding or updating an engine feature, the documentation team needs to 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 know about it. Contributors should open an issue on the `pandemonium-docs` repository
when their work gets merged and requires documentation. when their work gets merged and requires documentation.
@ -49,7 +44,6 @@ second title makes it clear what the purpose of signals is.
Note: Note:
Long section titles lead to long entries in the side menu, which can make 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. 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 may use signals, in which case we could note that the page that introduces
signals is a pre-requisite. signals is a pre-requisite.
Limiting cognitive load ### Limiting cognitive load
~~~~~~~~~~~~~~~~~~~~~~~
Limit the cognitive load required to read the documentation. The simpler and 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 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: Note:
Having programming foundations is a pre-requisite to use a complex engine Having programming foundations is a pre-requisite to use a complex engine
like Pandemonium. Talking about variables, functions, or classes is acceptable. like Pandemonium. Talking about variables, functions, or classes is acceptable.
But we should favor plain language over specific terminology like But we should favor plain language over specific terminology like

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 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 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 .. code:: sh
```
sphinx-build -b html ./ _build classes/class_node.rst classes/class_resource.rst 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 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 sphinx-build using virtualenv. To do so, run this command from this repository's
@ -98,8 +98,10 @@ root folder:
.. code:: sh .. code:: sh
```
virtualenv --system-site-packages env/ virtualenv --system-site-packages env/
. env/bin/activate . env/bin/activate
pip3 install -r requirements.txt pip3 install -r requirements.txt
```
Then, run `make html` as shown above. Then, run `make html` as shown above.

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 )` The class reference is available online in the `classes ( toc-class-ref )`
@ -19,7 +17,6 @@ taking care of a given class.
See also: See also:
You can find the writing guidelines for the class reference `here ( doc_class_reference_writing_guidelines )`. 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 For details on Git usage and the pull request workflow, please
@ -62,8 +59,7 @@ Warning:
scripts as described in scripts as described in
`doc_class_reference_writing_guidelines_editing_xml`. `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/`. 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