From 8e87dc1fe75b09409d5f27294720ce52aff20780 Mon Sep 17 00:00:00 2001 From: Relintai Date: Sat, 4 May 2024 00:04:16 +0200 Subject: [PATCH] Cleanups. --- .../21_assets_pipeline/01_import_process.md | 28 ++-- .../21_assets_pipeline/02_importing_images.md | 90 ++++-------- .../03_importing_audio_samples.md | 26 ++-- .../04_importing_translations.md | 30 ++-- .../21_assets_pipeline/05_importing_scenes.md | 135 ++++++------------ .../06_exporting_3d_scenes.md | 9 +- .../escn_exporter/01_introduction.md | 27 +--- .../escn_exporter/02_material.md | 19 ++- .../escn_exporter/03_physics.md | 20 ++- .../escn_exporter/04_lights.md | 7 +- .../escn_exporter/05_mesh.md | 12 +- .../escn_exporter/06_skeleton.md | 18 ++- .../escn_exporter/07_animation.md | 31 ++-- .../img/{in_godot.jpg => in_pandemonium.jpg} | Bin ...export.png => gltf_pandemonium_export.png} | Bin .../01_introduction_best_practices.md | 4 +- .../02_what_are_godot_classes.md | 10 +- .../03_scene_organization.md | 9 +- .../04_scenes_versus_scripts.md | 15 +- .../05_autoloads_versus_internal_nodes.md | 12 +- .../22_best_practices/06_node_alternatives.md | 4 +- .../07_pandemonium_interfaces.md | 11 +- .../08_pandemonium_notifications.md | 12 +- .../22_best_practices/09_data_preferences.md | 18 +-- .../22_best_practices/10_logic_preferences.md | 9 +- .../11_project_organization.md | 31 ++-- .../12_version_control_systems.md | 15 +- .../22_best_practices/13_list_of_tricks.md | 4 +- 04_modules/01_thread_pool.md | 37 +---- 04_modules/02_texture_packer.md | 33 ----- 04_modules/03_mesh_utils.md | 35 ----- 04_modules/04_mesh_data_resource.md | 33 ----- 04_modules/05_props.md | 34 ----- 04_modules/06_props_2d.md | 34 ----- 04_modules/07_terraman.md | 47 ------ 04_modules/08_terraman_2d.md | 51 ------- 04_modules/09_voxelman.md | 50 ------- 04_modules/10_entity_spell_system.md | 45 ------ 04_modules/11_skeleton_editor.md | 21 --- 04_modules/12_ui_extensions.md | 33 ----- .../img/autotile_template_2x2.png | Bin .../img/autotile_template_3x3_minimal.png | Bin .../img/autotile_template_3x3_minimal_16.png | Bin ...ile_template_3x3_minimal_topdown_floor.png | Bin ...ile_template_3x3_minimal_topdown_walls.png | Bin ...emplate_3x3_minimal_topdown_walls_tall.png | Bin ...mplate_3x3_minimal_topdown_walls_thick.png | Bin 04_modules/tile_maps/01_using_tilemaps.md | 47 ++---- .../tile_maps/img/autotile_template_2x2.png | Bin 0 -> 226 bytes .../img/autotile_template_3x3_minimal.png | Bin 0 -> 461 bytes .../img/autotile_template_3x3_minimal_16.png | Bin 0 -> 1312 bytes ...ile_template_3x3_minimal_topdown_floor.png | Bin 0 -> 812 bytes ...ile_template_3x3_minimal_topdown_walls.png | Bin 0 -> 769 bytes ...emplate_3x3_minimal_topdown_walls_tall.png | Bin 0 -> 1807 bytes ...mplate_3x3_minimal_topdown_walls_thick.png | Bin 0 -> 1151 bytes .../02_introduction_to_the_buildsystem.md | 14 +- .../01_compiling/04_compiling_for_x11.md | 3 +- .../01_compiling/09_compiling_for_uwp.md | 12 +- .../01_compiling/11_optimizing_for_size.md | 1 - ...introduction_to_pandemonium_development.md | 11 +- .../02_common_engine_methods_and_macros.md | 29 ++-- 05_engine_development/02_cpp/03_core_types.md | 54 +++---- .../02_cpp/04_variant_class.md | 15 +- .../02_cpp/05_object_class.md | 59 +++----- .../02_cpp/06_inheritance_class_tree.md | 21 ++- .../02_cpp/07_custom_modules_in_cpp.md | 49 +++---- .../08_binding_to_external_libraries.md | 18 +-- .../02_cpp/09_custom_pandemonium_servers.md | 41 ++---- .../10_custom_resource_format_loaders.md | 43 ++---- .../02_cpp/11_custom_audiostreams.md | 29 ++-- .../02_cpp/12_macos_debug.md | 10 +- .../02_cpp/13_using_cpp_profilers.md | 30 ++-- .../configuring_an_ide/01_android_studio.md | 16 +-- .../02_cpp/configuring_an_ide/02_clion.md | 27 ++-- .../configuring_an_ide/03_code_blocks.md | 82 +++-------- .../02_cpp/configuring_an_ide/04_kdevelop.md | 55 +++---- .../configuring_an_ide/05_qt_creator.md | 61 +++----- .../configuring_an_ide/06_visual_studio.md | 22 ++- .../07_visual_studio_code.md | 31 ++-- .../02_cpp/configuring_an_ide/08_xcode.md | 55 +++---- ...=> clion_5_select_pandemonium_process.png} | Bin ...ter_add_pandemonium_source_to_project.png} | Bin ...r_add_pandemonium_source_to_project_2.png} | Bin .../01_introduction_to_editor_development.md | 19 +-- .../03_editor/02_creating_icons.md | 21 +-- .../03_editor/03_editor_style_guide.md | 21 +-- .../04_file_formats/01_tscn.md | 39 ++--- 06_community/01_tutorials.md | 18 +-- 06_community/contributing/01_introduction.md | 77 ++-------- .../contributing/02_ways_to_contribute.md | 21 +-- ..._best_practices_for_engine_contributors.md | 36 ++--- 06_community/contributing/04_pr_workflow.md | 34 ++--- .../contributing/05_testing_pull_requests.md | 16 +-- .../contributing/06_bisecting_regressions.md | 15 +- .../contributing/07_bug_triage_guidelines.md | 15 +- .../contributing/08_code_style_guidelines.md | 53 +++---- .../contributing/09_cpp_usage_guidelines.md | 24 +--- .../contributing/10_content_guidelines.md | 16 +-- .../contributing/11_building_the_manual.md | 10 +- .../12_updating_the_class_reference.md | 8 +- .../13_class_reference_writing_guidelines.md | 54 ++----- .../14_editor_and_docs_localization.md | 43 ++---- .../15_contributing_to_the_documentation.md | 35 ++--- .../16_docs_writing_guidelines.md | 73 ++++------ .../17_documentation_guidelines.md | 21 +-- 105 files changed, 692 insertions(+), 1871 deletions(-) rename 03_usage/21_assets_pipeline/escn_exporter/img/{in_godot.jpg => in_pandemonium.jpg} (100%) rename 03_usage/21_assets_pipeline/img/{gltf_godot_export.png => gltf_pandemonium_export.png} (100%) rename {03_usage/02_2d => 04_modules/layered_tile_maps}/img/autotile_template_2x2.png (100%) rename {03_usage/02_2d => 04_modules/layered_tile_maps}/img/autotile_template_3x3_minimal.png (100%) rename {03_usage/02_2d => 04_modules/layered_tile_maps}/img/autotile_template_3x3_minimal_16.png (100%) rename {03_usage/02_2d => 04_modules/layered_tile_maps}/img/autotile_template_3x3_minimal_topdown_floor.png (100%) rename {03_usage/02_2d => 04_modules/layered_tile_maps}/img/autotile_template_3x3_minimal_topdown_walls.png (100%) rename {03_usage/02_2d => 04_modules/layered_tile_maps}/img/autotile_template_3x3_minimal_topdown_walls_tall.png (100%) rename {03_usage/02_2d => 04_modules/layered_tile_maps}/img/autotile_template_3x3_minimal_topdown_walls_thick.png (100%) create mode 100644 04_modules/tile_maps/img/autotile_template_2x2.png create mode 100644 04_modules/tile_maps/img/autotile_template_3x3_minimal.png create mode 100644 04_modules/tile_maps/img/autotile_template_3x3_minimal_16.png create mode 100644 04_modules/tile_maps/img/autotile_template_3x3_minimal_topdown_floor.png create mode 100644 04_modules/tile_maps/img/autotile_template_3x3_minimal_topdown_walls.png create mode 100644 04_modules/tile_maps/img/autotile_template_3x3_minimal_topdown_walls_tall.png create mode 100644 04_modules/tile_maps/img/autotile_template_3x3_minimal_topdown_walls_thick.png rename 05_engine_development/02_cpp/configuring_an_ide/img/{clion_5_select_godot_process.png => clion_5_select_pandemonium_process.png} (100%) rename 05_engine_development/02_cpp/configuring_an_ide/img/{xcode_5_after_add_godot_source_to_project.png => xcode_5_after_add_pandemonium_source_to_project.png} (100%) rename 05_engine_development/02_cpp/configuring_an_ide/img/{xcode_6_after_add_godot_source_to_project_2.png => xcode_6_after_add_pandemonium_source_to_project_2.png} (100%) diff --git a/03_usage/21_assets_pipeline/01_import_process.md b/03_usage/21_assets_pipeline/01_import_process.md index b67abec..94ee608 100644 --- a/03_usage/21_assets_pipeline/01_import_process.md +++ b/03_usage/21_assets_pipeline/01_import_process.md @@ -1,10 +1,7 @@ +# Import process -Import process -============== - -Importing assets in Pandemonium 3.0+ ------------------------------- +## Importing assets in Pandemonium 3.0+ Previously, importing assets in Pandemonium 2.x required manual maintenance of a separate directory with source assets. Without doing this, it was @@ -26,8 +23,7 @@ it will work in the editor, but break in the exported project. However, the `Resource Loader( ResourceLoader )` cannot access non imported files, only the `File` class can. -Changing import parameters --------------------------- +## Changing import parameters To change the import parameters of an asset in Pandemonium (again, keep in mind import parameters are only present in non-native Pandemonium resource types) @@ -42,8 +38,7 @@ Changing the import parameters of several assets at the same time is also possible. Simply select all of them together in the resources dock and the exposed parameters will apply to all of them when reimporting. -Reimporting multiple assets ---------------------------- +## Reimporting multiple assets While working on a project you may find that several assets need to have the same parameters changed, such as enabling mipmaps, but you only want @@ -58,15 +53,13 @@ assets, then change the parameters normally. Finally, click the reimport button and every selected asset will be reimported with only those parameters changed. -Automatic reimport ------------------- +## Automatic reimport When the MD5 checksum of the source asset changes, Pandemonium will perform an automatic reimport of it, applying the preset configured for that specific asset. -Files generated ------------------ +## Files generated Importing will add an extra `.import` file, containing the import configuration. Make sure to commit these to your version control system! @@ -83,8 +76,7 @@ to the version control system is optional. It can shorten reimporting time when checking out on another computer, but it takes considerably more space and transfer time. Pick your poison! -Changing import resource type ------------------------------ +## Changing import resource type Some source assets can be imported as different types of resources. For this, select the relevant type of resource desired and @@ -93,8 +85,7 @@ press "Reimport": ![](img/asset_workflow2.png) -Changing default import parameters ------------------------------------ +## Changing default import parameters Different types of games might require different defaults. Changing the defaults per project can be achieved by using the @@ -103,8 +94,7 @@ the default setting can be saved and cleared too: ![](img/asset_workflow3.png) -Simplicity is key! ------------------- +## Simplicity is key! This is a very simple workflow which should take very little time to get used to. It also enforces a more correct way to deal with resources. diff --git a/03_usage/21_assets_pipeline/02_importing_images.md b/03_usage/21_assets_pipeline/02_importing_images.md index 75644fb..b070ced 100644 --- a/03_usage/21_assets_pipeline/02_importing_images.md +++ b/03_usage/21_assets_pipeline/02_importing_images.md @@ -1,10 +1,8 @@ -Importing images -================ +# Importing images -Supported image formats ------------------------ +## Supported image formats Pandemonium can import the following image formats: @@ -37,8 +35,7 @@ Note: If you've compiled the Pandemonium editor from source with specific modules disabled, some formats may not be available. -Importing textures ------------------- +## Importing textures The default action in Pandemonium is to import images as textures. Textures are stored in video memory and can't be accessed directly. This is what makes drawing them @@ -48,20 +45,17 @@ Import options are vast: ![](img/image_import1.png) -Detect 3D -~~~~~~~~~ +### Detect 3D This option makes Pandemonium be aware of when a texture (which is imported for 2D as default) is used in 3D. If this happens, setting are changed so the texture flags are friendlier to 3D (mipmaps, filter and repeat become enabled and compression is changed to VRAM). Texture is also reimported automatically. -Compression ------------ +## Compression Images are one of the largest assets in a game. To handle them efficiently, they need to be compressed. Pandemonium offers several compression methods, depending on the use case. -Compress Mode -~~~~~~~~~~~~~ +### Compress Mode - **VRAM Compression:** This is the most common compression mode for 3D assets. Size on disk is reduced and video memory usage is also decreased considerably @@ -79,40 +73,26 @@ Compress Mode raw float images). In this table, each of the four options are described together with their -advantages and disadvantages (|good| = best, |bad| = worst): +advantages and disadvantages (![](img/good.png) = best, ![](img/bad.png) = worst): -+----------------+------------------------+-------------------------------+-------------------------+------------------------------------------------------+ | | Uncompressed | Compress Lossless | Compress Lossy | Compress VRAM | -+================+========================+===============================+=========================+======================================================+ +|----------------|------------------------|-------------------------------|-------------------------|------------------------------------------------------| | Description | Stored as raw pixels | Stored as Lossless WebP / PNG | Stored as Lossy WebP | Stored as S3TC/BC or PVRTC/ETC depending on platform | -+----------------+------------------------+-------------------------------+-------------------------+------------------------------------------------------+ -| Size on Disk | |bad| Large | |regular| Small | |good| Very Small | |regular| Small | -+----------------+------------------------+-------------------------------+-------------------------+------------------------------------------------------+ -| Memory Usage | |bad| Large | |bad| Large | |bad| Large | |good| Small | -+----------------+------------------------+-------------------------------+-------------------------+------------------------------------------------------+ -| Performance | |regular| Normal | |regular| Normal | |regular| Normal | |good| Fast | -+----------------+------------------------+-------------------------------+-------------------------+------------------------------------------------------+ -| Quality Loss | |good| None | |good| None | |regular| Slight | |bad| Moderate | -+----------------+------------------------+-------------------------------+-------------------------+------------------------------------------------------+ -| Load Time | |regular| Normal | |bad| Slow | |bad| Slow | |good| Fast | -+----------------+------------------------+-------------------------------+-------------------------+------------------------------------------------------+ +| Size on Disk | ![](img/bad.png) Large | ![](img/regular.png) Small | ![](img/good.png) Very Small | ![](img/regular.png) Small | +| Memory Usage | ![](img/bad.png) Large | ![](img/bad.png) Large | ![](img/bad.png) Large | ![](img/good.png) Small | +| Performance | ![](img/regular.png) Normal | ![](img/regular.png) Normal | ![](img/regular.png) Normal | ![](img/good.png) Fast | +| Quality Loss | ![](img/good.png) None | ![](img/good.png) None | ![](img/regular.png) Slight | ![](img/bad.png) Moderate | +| Load Time | ![](img/regular.png) Normal | ![](img/bad.png) Slow | ![](img/bad.png) Slow | ![](img/good.png) Fast | -.. |bad| image:: img/bad.png) -.. |good| image:: img/good.png) - -.. |regular| image:: img/regular.png) - -HDR Mode -~~~~~~~~ +### HDR Mode Pandemonium supports high dynamic range textures (as .HDR or .EXR). These are mostly useful as high dynamic range equirectangular panorama skies (the internet has plenty if you search for them), which replace Cubemaps in Pandemonium 2.x. Modern PCs support the BC6H VRAM format, but there are still plenty that do not. If you want Pandemonium to ensure full compatibility in terms of the kind of textures, enable the "Force RGBE" option. -Normal Map -~~~~~~~~~~ +### Normal Map When using a texture as normal map, only the red and green channels are required. Given regular texture compression algorithms produce artifacts that don't look that nice in normal maps, the RGTC compression format is the best fit for this data. Forcing this option to "Enabled" will make Pandemonium import the @@ -123,7 +103,6 @@ Note that RGTC compression affects the resulting normal map image. You will have Note: - Pandemonium requires the normal map to use the X+, Y+ and Z+ coordinates, this is known as OpenGL style. If you've imported a material made to be used with another engine it may be DirectX style, in which case the normal map needs to @@ -133,25 +112,21 @@ Note: popular engines) can be found `here ( http://wiki.polycount.com/wiki/Normal_Map_Technical_Details )`. -Flags ------ +## Flags There are plenty of settings that can be toggled when importing an image as a texture, depending on the use case. -Repeat -~~~~~~ +### Repeat This setting is most commonly used in 3D, and is therefore generally disabled in 2D. It sets UV coordinates going beyond the 0,0 - 1,1 range to "loop". Repeating can optionally be set to mirrored mode. -Filter -~~~~~~ +### Filter When pixels become larger than the screen pixels, this option enables linear interpolation for them. The result is a smoother (less blocky) texture. This setting can be commonly used in 2D and 3D, but it's usually disabled when making pixel perfect games. -Mipmaps -~~~~~~~ +### Mipmaps When pixels become smaller than the screen, mipmaps kick in. This helps reduce the grainy effect when shrinking the textures. Keep in mind that, in older hardware (GLES2, mainly mobile), there are some requirements to use mipmaps: @@ -163,13 +138,11 @@ Keep in mind the above when making phone games and applications, want to aim for When doing 3D, mipmap should be turned on, as this also improves performance (smaller versions of the texture are used for objects further away). -Anisotropic -~~~~~~~~~~~ +### Anisotropic When textures are near parallel to the view (like floors), this option makes them have more detail by reducing blurriness. -sRGB -~~~~ +### sRGB Pandemonium uses Linear colorspace when rendering 3D. Textures mapped to albedo or detail channels need to have this option turned on in order for colors to look correct. When set to **Detect** mode, the texture will be marked as sRGB when used in albedo channels. @@ -185,13 +158,11 @@ Warning: sRGB on one of the copies only. Use the copy with sRGB enabled in 3D, and the copy with sRGB disabled in 2D. -Process -------- +## Process Some special processes can be applied to images when imported as textures. -Fix Alpha Border -~~~~~~~~~~~~~~~~ +### Fix Alpha Border This puts pixels of the same surrounding color in transition from transparency to non transparency. It helps mitigate the outline effect when exporting images from Photoshop and the like. @@ -200,26 +171,21 @@ from Photoshop and the like. It's a good idea to leave it on by default, unless specific values are needed. -Premultiplied Alpha -~~~~~~~~~~~~~~~~~~~ +### Premultiplied Alpha An alternative to fix darkened borders is to use premultiplied alpha. By enabling this option, the texture will be converted to this format. Keep in mind that a material will need to be created that uses the PREMULT ALPHA blend mode on canvas items that need it. -HDR as sRGB -~~~~~~~~~~~ +### HDR as sRGB A few HDR files are broken and contain sRGB color data. It is advised not to use them, but, in the worst-case scenario, toggling this option on will make them look right. -Invert Color -~~~~~~~~~~~~ +### Invert Color Reverses the image's color. This is useful, for example, to convert a height map generated by external programs to depth map to use with `doc_spatial_material`. -Svg ---- +## Svg -Scale -~~~~~ +### Scale This option only applies to SVG files. It controls the scale of the SVG image. The default scale (1.0) will make the imported SVG match its original design scale. diff --git a/03_usage/21_assets_pipeline/03_importing_audio_samples.md b/03_usage/21_assets_pipeline/03_importing_audio_samples.md index 1bc6613..320ff42 100644 --- a/03_usage/21_assets_pipeline/03_importing_audio_samples.md +++ b/03_usage/21_assets_pipeline/03_importing_audio_samples.md @@ -1,10 +1,8 @@ -Importing audio samples -======================= +# Importing audio samples -Supported files ---------------- +## Supported files Pandemonium provides three options to import your audio data: WAV, Ogg Vorbis and MP3. @@ -27,27 +25,21 @@ Each has different advantages. Here is a comparative chart. -+-----------------------------+-------------------+ + | Format | 1 second of audio | -+=============================+===================+ +|-----------------------------|-------------------| | WAV 24-bit, 96 kHz, stereo | 576 KB | -+-----------------------------+-------------------+ | WAV 16-bit, 44 kHz, mono | 88 KB | -+-----------------------------+-------------------+ | WAV 16-bit, IMA-ADPCM, mono | 22 KB | -+-----------------------------+-------------------+ | MP3 192 Kb/s, stereo | 24 KB | -+-----------------------------+-------------------+ | Ogg Vorbis 128 Kb/s, stereo | 16 KB | -+-----------------------------+-------------------+ | Ogg Vorbis 96 Kb/s, stereo | 12 KB | -+-----------------------------+-------------------+ + Consider using WAV for short and repetitive sound effects, and Ogg Vorbis for music, speech, and long sound effects. -Best practices --------------- +## Best practices Pandemonium has an `extensive bus system ( doc_audio_buses )` with built-in effects. This saves SFX artists the need to add reverb to the sound effects, @@ -58,8 +50,7 @@ with baked reverb! As you can see above, sound effects become huge with reverb added. -Trimming -~~~~~~~~ +### Trimming One issue that happens often is that the waveform is exported with long silences at the beginning and at the end. These are inserted by @@ -69,8 +60,7 @@ add latency to the moment they are played back. Importing as WAV with the **Trimming** option enabled solves this. -Looping -~~~~~~~ +### Looping Pandemonium supports looping in the samples (tools such as Sound Forge or Audition can add loop points to WAV files). This is useful for sound diff --git a/03_usage/21_assets_pipeline/04_importing_translations.md b/03_usage/21_assets_pipeline/04_importing_translations.md index 4ae1474..02e12eb 100644 --- a/03_usage/21_assets_pipeline/04_importing_translations.md +++ b/03_usage/21_assets_pipeline/04_importing_translations.md @@ -1,10 +1,7 @@ +# Importing translations -Importing translations -====================== - -Games and internationalization ------------------------------- +## Games and internationalization The world is full of different languages and cultures, so nowadays games are released in several languages. To handle this, internationalized text @@ -34,8 +31,7 @@ Note: loading translations written in the gettext `.po` format. See `doc_localization_using_gettext` for details. -Translation format ------------------- +## Translation format To complete the picture and allow efficient support for translations, Pandemonium has a special importer that can read CSV files. Most spreadsheet @@ -55,15 +51,13 @@ Warning: CSV files must be formatted as follows: -+--------+----------+----------+----------+ + | keys | | | | -+========+==========+==========+==========+ +|--------|----------|----------|----------| | KEY1 | string | string | string | -+--------+----------+----------+----------+ | KEY2 | string | string | string | -+--------+----------+----------+----------+ | KEYN | string | string | string | -+--------+----------+----------+----------+ + The "lang" tags must represent a language, which must be one of the `valid locales ( doc_locales )` supported by the engine. The "KEY" tags must be @@ -74,17 +68,14 @@ runtime by the matching translated string. Note that the case is important, The top-left cell is ignored and can be left empty or having any content. Here's an example: -+-------+-----------------------+------------------------+------------------------------+ + | keys | en | es | ja | -+=======+=======================+========================+==============================+ +|-------|-----------------------|------------------------|------------------------------| | GREET | Hello, friend! | Hola, amigo! | こんにちは | -+-------+-----------------------+------------------------+------------------------------+ | ASK | How are you? | Cómo está? | 元気ですか | -+-------+-----------------------+------------------------+------------------------------+ | BYE | Goodbye | Adiós | さようなら | -+-------+-----------------------+------------------------+------------------------------+ | QUOTE | "Hello" said the man. | "Hola" dijo el hombre. | 「こんにちは」男は言いました | -+-------+-----------------------+------------------------+------------------------------+ + The same example is shown below as a comma-separated plain text file, which should be the result of editing the above in a spreadsheet. @@ -104,8 +95,7 @@ comma in the import options. QUOTE,"""Hello"" said the man.","""Hola"" dijo el hombre.",「こんにちは」男は言いました ``` -CSV importer ------------- +## CSV importer Pandemonium will treat CSV files as translations by default. It will import them and generate one or more compressed translation resource files next to it. diff --git a/03_usage/21_assets_pipeline/05_importing_scenes.md b/03_usage/21_assets_pipeline/05_importing_scenes.md index 96bd759..2e71a72 100644 --- a/03_usage/21_assets_pipeline/05_importing_scenes.md +++ b/03_usage/21_assets_pipeline/05_importing_scenes.md @@ -1,10 +1,8 @@ -Importing 3D scenes -=================== +# Importing 3D scenes -Pandemonium scene importer --------------------- +## Pandemonium scene importer When dealing with 3D assets, Pandemonium has a flexible and configurable importer. @@ -25,8 +23,7 @@ Just copy the scene file together with the texture to the project repository, an It is important that the mesh is not deformed by bones when exporting. Make sure that the skeleton is reset to its T-pose or default rest pose before exporting with your favorite 3D editor. -Exporting DAE files from Maya and 3DS Max -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +### Exporting DAE files from Maya and 3DS Max Autodesk added built-in COLLADA support to Maya and 3DS Max, but it's broken by default and should not be used. The best way to export this format @@ -35,8 +32,7 @@ is by using the plugins. They work well, although they are not always up-to date with the latest version of the software. -Exporting glTF 2.0 files from Blender -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +### Exporting glTF 2.0 files from Blender There are three ways to export glTF files from Blender. As a glTF binary (`.glb` file), glTF embedded (`.gltf` file), and with textures (`gltf` + `.bin` + textures). @@ -54,12 +50,10 @@ either of those glTF binary files are fine. Warning: - Blend shape animations cannot be imported - they require manual animation within Pandemonium. Note: - Blender versions older than 3.2 do not export emissive textures with the glTF file. If your model uses one and you're using an older version of Blender, it must be brought in separately. @@ -71,8 +65,7 @@ Note: being culled by other faces. To resolve this, enable **Backface Culling** in Blender's Materials tab, then export the scene to glTF again. -Exporting DAE files from Blender -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +### Exporting DAE files from Blender Blender has built-in COLLADA support, but it does not work properly for the needs of game engines and should not be used as is. @@ -81,8 +74,7 @@ Pandemonium provides a `Blender plugin ( https://github.com/pandemoniumengine/co that will correctly export COLLADA scenes for use in Pandemonium. It does not work in Blender 2.8 or newer, but there are plans to update it in the future. -Exporting ESCN files from Blender -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +### Exporting ESCN files from Blender The most powerful one, called `pandemonium-blender-exporter ( https://github.com/Relintai/pandemonium_engine-blender-exporter )`. @@ -90,11 +82,10 @@ It uses a .escn file, which is kind of another name for a .tscn file (Pandemoniu it keeps as much information as possible from a Blender scene. However, it is considered experimental. -The ESCN exporter has a detailed `document Storage** to **Built-In** instead of **Files**. -Keep On Reimport -^^^^^^^^^^^^^^^^ +#### Keep On Reimport Once materials are edited to use Pandemonium features, the importer will keep the edited ones and ignore the ones coming from the source scene. This option is only present if materials are saved as files. -Meshes -~~~~~~ +### Meshes -Compress -^^^^^^^^ +#### Compress Makes meshes use less precise numbers for multiple aspects of the mesh in order to save space. @@ -265,16 +240,14 @@ may be needed. For instance, if a mesh is very big or there are multiple meshes being imported that cover a large area, compressing the import of this mesh(es) may lead to gaps in geometry or vertices not being exactly where they should be. -Ensure Tangents -^^^^^^^^^^^^^^^ +#### Ensure Tangents If textures with normal mapping are to be used, meshes need to have tangent arrays. This option ensures that these are generated if not present in the source scene. Pandemonium uses `Mikktspace ( http://www.mikktspace.com/ )` for this, but it's always better to have them generated in the exporter. -Storage -^^^^^^^ +#### Storage Meshes can be stored in separate files (resources) instead of built-in. This does not have much practical use unless one wants to build objects with them directly. @@ -282,8 +255,7 @@ not have much practical use unless one wants to build objects with them directly This option is provided to help those who prefer working directly with meshes instead of scenes. -Light Baking -^^^^^^^^^^^^ +#### Light Baking Whether or not the mesh is used in baked lightmaps. @@ -294,14 +266,12 @@ Whether or not the mesh is used in baked lightmaps. Note: For more information on light baking see `doc_baked_lightmaps`. -External Files -~~~~~~~~~~~~~~ +### External Files Generated meshes and materials can be optionally stored in a subdirectory with the name of the scene. -Animation options ------------------ +## Animation options Pandemonium provides many options regarding how animation data is dealt with. Some exporters (such as Blender) can generate many animations in a single file. Others, such as @@ -312,21 +282,19 @@ each animation in a separate file. Import of animations is enabled by default. -.. attention:: +Attention: To modify animations from an imported 3D scene, you need to change the animation storage option from **Built-In** to **Files** in the Import dock. Otherwise, changes made to animations from Pandemonium will be lost when the project is run. -FPS -~~~ +### FPS Most 3D export formats store animation timeline in seconds instead of frames. To ensure animations are imported as faithfully as possible, please specify the frames per second used to edit them. Failing to do this may result in shaky animations. -Filter Script -~~~~~~~~~~~~~ +### Filter Script It is possible to specify a filter script in a special syntax to decide which tracks from which animations should be kept. @@ -378,31 +346,27 @@ as `"Skeleton:Head"` or `"Skeleton:Arm_Left_Control"` would be retained. Any track filter lines that do not begin with a `+` or `-` are ignored. -Storage -~~~~~~~ +### Storage By default, animations are saved as built-in. It is possible to save them to a file instead. This allows adding custom tracks to the animations and keeping them after a reimport. -Optimizer -~~~~~~~~~ +### Optimizer When animations are imported, an optimizer is run, which reduces the size of the animation considerably. In general, this should always be turned on unless you suspect that an animation might be broken due to it being enabled. -Clips -~~~~~ +### Clips It is possible to specify multiple animations from a single timeline as clips. For this to work, the model must have only one animation that is named `default`. To create clips, change the clip amount to something greater than zero. You can then name a clip, specify which frames it starts and stops on, and choose whether the animation loops or not. -.. If this PR (https://github.com/Relintai/pandemonium_engine/pull/36709) is merged for Pandemonium 4.0 this section must +If this PR (https://github.com/Relintai/pandemonium_engine/pull/36709) is merged for Pandemonium 4.0 this section must be updated to reflect that for the 4.0 documentation. -Scene inheritance ------------------ +## Scene inheritance In many cases, it may be desired to make modifications to the imported scene. By default, this is not possible because if the source asset changes (source `.dae`, `.gltf`, `.obj` file re-exported from 3D modelling app), Pandemonium will re-import the whole scene. @@ -421,8 +385,7 @@ Other than that, everything is allowed! -Import hints ------------- +## Import hints Many times, when editing a scene, there are common tasks that need to be done after exporting: @@ -436,17 +399,14 @@ will detect suffixes in object names and will perform actions automatically. Note: - All the suffixes described below are *case-sensitive*. -Remove nodes (-noimp) -~~~~~~~~~~~~~~~~~~~~~ +### Remove nodes (-noimp) Objects that have the `-noimp` suffix will be removed at import-time no matter what their type is. They will not appear in the imported scene. -Create collisions (-col, -convcol, -colonly, -convcolonly) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +### Create collisions (-col, -convcol, -colonly, -convcolonly) The option `-col` will work only for Mesh objects. If it is detected, a child static collision node will be added, using the same geometry as the mesh. This @@ -491,42 +451,35 @@ reliability. Note: - For better visibility in Blender's editor, you can set the "X-Ray" option on collision empties and set some distinct color for them in Blender's **User Preferences > Themes > 3D View > Empty**. See also: - See `doc_collision_shapes_3d` for a comprehensive overview of collision shapes. -Create navigation (-navmesh) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +### Create navigation (-navmesh) A mesh node with the `-navmesh` suffix will be converted to a navigation mesh. The original Mesh object will be removed at import-time. -Create a VehicleBody (-vehicle) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +### Create a VehicleBody (-vehicle) A mesh node with the `-vehicle` suffix will be imported as a child to a `VehicleBody` node. -Create a VehicleWheel (-wheel) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +### Create a VehicleWheel (-wheel) A mesh node with the `-wheel` suffix will be imported as a child to a `VehicleWheel` node. -Rigid Body (-rigid) -~~~~~~~~~~~~~~~~~~~ +### Rigid Body (-rigid) A mesh node with the `-rigid` suffix will be imported as a `RigidBody`. -Animation loop (-loop, -cycle) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +### Animation loop (-loop, -cycle) Animation clips in the COLLADA document that start or end with the token `loop` or `cycle` will be imported as a Pandemonium Animation with the loop flag set. diff --git a/03_usage/21_assets_pipeline/06_exporting_3d_scenes.md b/03_usage/21_assets_pipeline/06_exporting_3d_scenes.md index 18a2074..47ae96a 100644 --- a/03_usage/21_assets_pipeline/06_exporting_3d_scenes.md +++ b/03_usage/21_assets_pipeline/06_exporting_3d_scenes.md @@ -1,10 +1,8 @@ -Exporting 3D scenes -=================== +# Exporting 3D scenes -Overview --------- +## Overview In Pandemonium it is possible to export 3D scenes as a glTF 2.0 file. You can export as a glTF binary (`.glb` file) or glTF embedded with textures @@ -21,8 +19,7 @@ To export a scene in the editor go to **Project > Tools > Export GLTF...** ![](img/gltf_pandemonium_export.png) -Limitations ------------ +## Limitations There are several limitations with glTF export. diff --git a/03_usage/21_assets_pipeline/escn_exporter/01_introduction.md b/03_usage/21_assets_pipeline/escn_exporter/01_introduction.md index d626231..d4f5392 100644 --- a/03_usage/21_assets_pipeline/escn_exporter/01_introduction.md +++ b/03_usage/21_assets_pipeline/escn_exporter/01_introduction.md @@ -1,5 +1,5 @@ -Blender ESCN exporter -===================== + +# Blender ESCN exporter Note: This chapter relates to the Blender plugin called "Pandemonium Blender Exporter", @@ -9,36 +9,19 @@ This plugin can be used to export Blender scenes in a Pandemonium-specific scene called ESCN, which is similar to TSCN (text format) but will be imported as binary SCN for performance. -Details on exporting --------------------- - -.. toctree:: - :maxdepth: 1 - :name: toc-learn-workflow-assets-escn_exporter - - material - physics - lights - mesh - skeleton - animation - - -Disabling specific objects --------------------------- +## Disabling specific objects Sometimes you don't want some objects exported (e.g. high-res models used for baking). An object will not be exported if it is not rendered in the scene. This can be set in the outliner: -![](img/hide.jpg +![](img/hide.jpg) Objects hidden in the viewport will be exported, but will be hidden in the Pandemonium scene. -Build pipeline integration --------------------------- +## Build pipeline integration If you have hundreds of model files, you don't want your artists to waste time manually exporting their blend files. To combat this, the exporter provides a diff --git a/03_usage/21_assets_pipeline/escn_exporter/02_material.md b/03_usage/21_assets_pipeline/escn_exporter/02_material.md index 59e0f42..39bb199 100644 --- a/03_usage/21_assets_pipeline/escn_exporter/02_material.md +++ b/03_usage/21_assets_pipeline/escn_exporter/02_material.md @@ -1,8 +1,7 @@ -Materials -========= -Using existing Pandemonium materials ------------------------------- +# Materials + +## Using existing Pandemonium materials One way in which the exporter can handle materials is to attempt to match the Blender material with an existing Pandemonium material. This has the advantage of @@ -20,7 +19,7 @@ exporter will fall back to exporting the material from Blender. Where the exporter searches for the `.tres` file is determined by the "Material Search Paths" option: -![](img/material_search.jpg +![](img/material_search.jpg) This can take the value of: - Project Directory - Attempts to find the `project.Pandemonium` and recursively @@ -33,8 +32,7 @@ This can take the value of: - None - Do not search for materials. Export them from the Blender file. -Export of Cycles/EEVEE materials --------------------------------- +## Export of Cycles/EEVEE materials The exporter has a primitive support for converting Cycles/EEVEE material node tree to Pandemonium Shader Material. Note that some of the Shader Node are not supported yet due to @@ -56,15 +54,14 @@ is using Blender Internal Engine, only the diffuse color and a few flags (e.g. u exported and form a Spatial Material. -Generate external materials ---------------------------- +## Generate external materials The default configuration of material exporting would keep all the materials internal to the `escn` file. There is an option which could enable generating external `.material` file when the `escn` file opens in Pandemonium. -![](img/external_mat_option.jpg +![](img/external_mat_option.jpg) `.material` file can be assigned to any material slot to be a external resource. -![](img/gd_dot_material.jpg +![](img/gd_dot_material.jpg) diff --git a/03_usage/21_assets_pipeline/escn_exporter/03_physics.md b/03_usage/21_assets_pipeline/escn_exporter/03_physics.md index ce7e30f..e06c149 100644 --- a/03_usage/21_assets_pipeline/escn_exporter/03_physics.md +++ b/03_usage/21_assets_pipeline/escn_exporter/03_physics.md @@ -1,33 +1,32 @@ -Physics properties -================== + +# Physics properties Exporting physics properties is done by enabling "Rigid Body" in Blender's physics tab: ![](img/enable_physics.png) -.. important:: +Important: + By default, a single Blender object with rigid body enabled will export as three nodes: a PhysicsBody, a CollisionShape, and a MeshInstance. -Body type ---------- +## Body type Blender only has the concept of "Active" and "Passive" rigid bodies. These turn into Static and RigidBody nodes. To create a kinematic body, enable the "animated" checkbox on an "Active" body: -![](img/body_type.jpg +![](img/body_type.jpg) -Collision shapes ----------------- +## Collision shapes Many of the parameters for collision shapes are missing from Blender, and many of the collision shapes are also not present. However, almost all of the options in Blender's rigid body collision and rigid body dynamics interfaces are supported: -![](img/collision_shapes.jpg +![](img/collision_shapes.jpg) There are the following caveats: - Not all of the collision shapes are supported. Only `Mesh`, `Convex @@ -43,8 +42,7 @@ There are the following caveats: rigid body enabled. The physics properties are taken from the parent-most rigid body, and the rest are used as collision shapes. -Collision geometry only ------------------------ +## Collision geometry only Frequently you want different geometry for your collision meshes and your graphical meshes, but by default, the exporter will export a mesh along with the diff --git a/03_usage/21_assets_pipeline/escn_exporter/04_lights.md b/03_usage/21_assets_pipeline/escn_exporter/04_lights.md index 38ef32e..32134e5 100644 --- a/03_usage/21_assets_pipeline/escn_exporter/04_lights.md +++ b/03_usage/21_assets_pipeline/escn_exporter/04_lights.md @@ -1,5 +1,6 @@ -Lights -====== + +# Lights + Warning: By default, lamps in Blender have shadows enabled. This can cause @@ -13,7 +14,7 @@ Warning: Sun, point and spot lamps are all exported from Blender along with many of their properties: -![](img/light_properties.jpg +![](img/light_properties.jpg) There are some things to note: diff --git a/03_usage/21_assets_pipeline/escn_exporter/05_mesh.md b/03_usage/21_assets_pipeline/escn_exporter/05_mesh.md index f605bea..78acb3a 100644 --- a/03_usage/21_assets_pipeline/escn_exporter/05_mesh.md +++ b/03_usage/21_assets_pipeline/escn_exporter/05_mesh.md @@ -1,14 +1,14 @@ -Mesh -==== -Modifiers ---------- +# Mesh + +## Modifiers + There is an exporting option :code:`Apply Modifiers` to control whether mesh modifiers are applied to the exported mesh. -Shape Key ---------- +## Shape Key + Exporting mesh shape key is supported, however exporting each shape key is almost like exporting the mesh again, so don't be surprised it takes a relatively long time. diff --git a/03_usage/21_assets_pipeline/escn_exporter/06_skeleton.md b/03_usage/21_assets_pipeline/escn_exporter/06_skeleton.md index d05a4c7..e35bd64 100644 --- a/03_usage/21_assets_pipeline/escn_exporter/06_skeleton.md +++ b/03_usage/21_assets_pipeline/escn_exporter/06_skeleton.md @@ -1,10 +1,10 @@ -Skeleton + +# Skeleton ======== -![](img/armature.jpg +![](img/armature.jpg) -Rest Bone ---------- +## Rest Bone Armature object in Blender is exported as a Skeleton node along with rest position (transform in Pandemonium) of bones. @@ -19,23 +19,21 @@ Warning: It is important that the mesh is not deformed by bones when exporting in Blender. Make sure that the skeleton is reset to its T-pose or default rest pose. -Bone Weights ------------- +## Bone Weights Blender put rigged mesh vertices which has no bone weights at its original position, but these vertices would be placed at (0, 0, 0) in Pandemonium, making the mesh deformed. Therefore, the exporter would raise an error for any vertex with no bone weights detected in a rigged mesh. -Non-Deform Bone ---------------- +## Non-Deform Bone Note that the non-deform bone can be configured as not exported by enabling the :code:`Exclude Control Bones`; the deform bone checkbox is shown in the picture. -Bone Attachment ---------------- +## Bone Attachment + A bone can be the parent of an object in Blender; this relation is exported as a BoneAttachment node in the Pandemonium scene. diff --git a/03_usage/21_assets_pipeline/escn_exporter/07_animation.md b/03_usage/21_assets_pipeline/escn_exporter/07_animation.md index 0a8f12e..d74b090 100644 --- a/03_usage/21_assets_pipeline/escn_exporter/07_animation.md +++ b/03_usage/21_assets_pipeline/escn_exporter/07_animation.md @@ -1,5 +1,6 @@ -Animation -========= + +# Animation + Animation supported: - transform animation of all types of objects - transform animation of pose bones @@ -7,8 +8,8 @@ Animation supported: - light animation - camera animation -Multiple Actions For Single Object ----------------------------------- +## Multiple Actions For Single Object + In most games, one object would have several animations to switch between. This add-on has support for exporting multiple actions all at once into a single AnimationPlayer and makes it easy to switch actions. @@ -22,13 +23,13 @@ New created action is always an active action bound to object. There are several ways to place an active action into NLA track, one is of course doing it in `NLA Editor` -![](img/nla_editor.jpg -![](img/nla_pushdown.jpg +![](img/nla_editor.jpg) +![](img/nla_pushdown.jpg) Or it can be done stashing the action in `Dope Sheet` -![](img/dope_sheet.jpg -![](img/stash_action.jpg +![](img/dope_sheet.jpg) +![](img/stash_action.jpg) **2. Check mute status of NLA tracks** @@ -36,30 +37,30 @@ An NLA track can be `mute` or `unmute`, the exporter will export all the `mute` NLA track as a separate action, while blends all the `unmute` NLA tracks into every action (including the action action) being exported. -![](img/nla_strip.jpg +![](img/nla_strip.jpg) **3. Export the scene** Make sure the `Export Stashed Actions` option has been turned on. -![](img/stash_action_option.jpg +![](img/stash_action_option.jpg) Then all the stashed actions, as well as the active action, are exported to an AnimationPlayer. -![](img/in_pandemonium.jpg +![](img/in_pandemonium.jpg) -Constraints ------------ +## Constraints + Sometimes complicated animation is built with object constraint; a usual example is inverse kinematics. The add-on would automatically check if an object has some constraint; if it does, all the constraints are baked into actions and then exported along with the object. -Animation Mode ---------------------------- +## Animation Mode + Pandemonium and Blender have different structure to store animation data. In Pandemonium animation data is stored in an AnimationPlayer node, instead of in each animated node. In order to fix this inconsistence and still diff --git a/03_usage/21_assets_pipeline/escn_exporter/img/in_godot.jpg b/03_usage/21_assets_pipeline/escn_exporter/img/in_pandemonium.jpg similarity index 100% rename from 03_usage/21_assets_pipeline/escn_exporter/img/in_godot.jpg rename to 03_usage/21_assets_pipeline/escn_exporter/img/in_pandemonium.jpg diff --git a/03_usage/21_assets_pipeline/img/gltf_godot_export.png b/03_usage/21_assets_pipeline/img/gltf_pandemonium_export.png similarity index 100% rename from 03_usage/21_assets_pipeline/img/gltf_godot_export.png rename to 03_usage/21_assets_pipeline/img/gltf_pandemonium_export.png diff --git a/03_usage/22_best_practices/01_introduction_best_practices.md b/03_usage/22_best_practices/01_introduction_best_practices.md index a973868..125c86a 100644 --- a/03_usage/22_best_practices/01_introduction_best_practices.md +++ b/03_usage/22_best_practices/01_introduction_best_practices.md @@ -1,7 +1,6 @@ -Introduction -============ +# Introduction This series is a collection of best practices to help you work efficiently with Pandemonium. @@ -23,7 +22,6 @@ Object-Oriented programming languages. It will help you make sense of the rest o Note: - The best practices in Pandemonium rely on Object-Oriented design principles. We use tools like the `single responsibility ( https://en.wikipedia.org/wiki/Single_responsibility_principle )` principle and diff --git a/03_usage/22_best_practices/02_what_are_godot_classes.md b/03_usage/22_best_practices/02_what_are_godot_classes.md index 55c2f1d..13fbda7 100644 --- a/03_usage/22_best_practices/02_what_are_godot_classes.md +++ b/03_usage/22_best_practices/02_what_are_godot_classes.md @@ -1,7 +1,5 @@ - -Applying object-oriented principles in Pandemonium -============================================ +# Applying object-oriented principles in Pandemonium The engine offers two main ways to create reusable objects: scripts and scenes. Neither of these technically define classes under the hood. @@ -13,8 +11,7 @@ think of them as classes. This guide briefly explains how scripts and scenes work in the engine's core to help you understand how they work under the hood. -How scripts work in the engine ------------------------------- +## How scripts work in the engine The engine provides built-in classes like `Node`. You can extend those to create derived types using a script. @@ -46,8 +43,7 @@ Note: `extends` keyword from code. Since they extend `Reference` though, you cannot attach them to a `Node`. -Scenes ------- +## Scenes The behavior of scenes has many similarities to classes, so it can make sense to think of a scene as a class. Scenes are reusable, instantiable, and inheritable groups of nodes. Creating a scene is diff --git a/03_usage/22_best_practices/03_scene_organization.md b/03_usage/22_best_practices/03_scene_organization.md index 4aef902..d7084b5 100644 --- a/03_usage/22_best_practices/03_scene_organization.md +++ b/03_usage/22_best_practices/03_scene_organization.md @@ -1,14 +1,12 @@ -Scene organization -================== +# Scene organization This article covers topics related to the effective organization of scene content. Which nodes should one use? Where should one place them? How should they interact? -How to build relationships effectively --------------------------------------- +## How to build relationships effectively When Pandemonium users begin crafting their own scenes, they often run into the following problem: @@ -190,8 +188,7 @@ by *all* OOP principles. Examples include... - `KISS ( https://en.wikipedia.org/wiki/KISS_principle )` - `YAGNI ( https://en.wikipedia.org/wiki/You_aren%27t_gonna_need_it )` -Choosing a node tree structure ------------------------------- +## Choosing a node tree structure So, a developer starts work on a game only to stop at the vast possibilities before them. They might know what they want to do, what systems they want to diff --git a/03_usage/22_best_practices/04_scenes_versus_scripts.md b/03_usage/22_best_practices/04_scenes_versus_scripts.md index c8fab5f..b3e0759 100644 --- a/03_usage/22_best_practices/04_scenes_versus_scripts.md +++ b/03_usage/22_best_practices/04_scenes_versus_scripts.md @@ -1,7 +1,6 @@ -When to use scenes versus scripts -================================= +# When to use scenes versus scripts We've already covered how scenes and scripts are different. Scripts define an engine class extension with imperative code, scenes with @@ -12,8 +11,7 @@ Scenes can define how an extended class initializes, but not what its behavior actually is. Scenes are often used in conjunction with a script so that the scene acts as an extension of the scripts declarative code. -Anonymous types ---------------- +## Anonymous types It *is* possible to completely define a scenes' contents using a script alone. This is, in essence, what the Pandemonium Editor does, only in the C++ constructor @@ -38,8 +36,7 @@ Also, scripts will operate a little slower than scenes due to the speed differences between engine and script code. The larger and more complex the node, the more reason there is to build it as a scene. -Named types ------------ +## Named types In some cases, a user can register a script as a new type within the editor itself. This displays it as a new type in the node or resource creation dialog @@ -125,8 +122,7 @@ this way. On the downside, it also means having to use largely imperative programming. -Performance of Script vs PackedScene ------------------------------------- +## Performance of Script vs PackedScene One last aspect to consider when choosing scenes and scripts is execution speed. @@ -161,8 +157,7 @@ Scenes help to avoid this performance issue. `PackedScene that use serialized data to create objects. The engine can process scenes in batches on the back-end and provide much better performance than scripts. -Conclusion ----------- +## Conclusion In the end, the best approach is to consider the following: diff --git a/03_usage/22_best_practices/05_autoloads_versus_internal_nodes.md b/03_usage/22_best_practices/05_autoloads_versus_internal_nodes.md index b25183b..03a7945 100644 --- a/03_usage/22_best_practices/05_autoloads_versus_internal_nodes.md +++ b/03_usage/22_best_practices/05_autoloads_versus_internal_nodes.md @@ -1,7 +1,6 @@ -Autoloads versus regular nodes -============================== +# Autoloads versus regular nodes Pandemonium offers a feature to automatically load nodes at the root of your project, allowing you to access them globally, that can fulfill the role of a Singleton: @@ -11,8 +10,7 @@ change the scene from code with `SceneTree.change_scene`. In this guide, you will learn when to use the Autoload feature, and techniques you can use to avoid it. -The cutting audio issue ------------------------ +## The cutting audio issue Other engines can encourage the use of creating manager classes, singletons that organize a lot of functionality into a globally accessible object. Pandemonium offers @@ -61,8 +59,7 @@ needs within itself and all these problems go away: 3. Each scene allocates exactly the amount of resources it needs. -Managing shared functionality or data -------------------------------------- +## Managing shared functionality or data Another reason to use an Autoload can be that you want to reuse the same method or data across many scenes. @@ -78,8 +75,7 @@ When it comes to data, you can either: 2. Store the data in an object to which each node has access, for example using the `owner` property to access the scene's root node. -When you should use an Autoload -------------------------------- +## When you should use an Autoload Auto-loaded nodes can simplify your code in some cases: diff --git a/03_usage/22_best_practices/06_node_alternatives.md b/03_usage/22_best_practices/06_node_alternatives.md index 661defb..fb1c1f7 100644 --- a/03_usage/22_best_practices/06_node_alternatives.md +++ b/03_usage/22_best_practices/06_node_alternatives.md @@ -1,8 +1,6 @@ -When and how to avoid using nodes for everything -================================================ - +# When and how to avoid using nodes for everything Nodes are cheap to produce, but even they have their limits. A project may have tens of thousands of nodes all doing things. The more complex their diff --git a/03_usage/22_best_practices/07_pandemonium_interfaces.md b/03_usage/22_best_practices/07_pandemonium_interfaces.md index 588ee99..f5de94e 100644 --- a/03_usage/22_best_practices/07_pandemonium_interfaces.md +++ b/03_usage/22_best_practices/07_pandemonium_interfaces.md @@ -1,7 +1,6 @@ -Pandemonium interfaces -================ +# Pandemonium interfaces Often one needs scripts that rely on other objects for features. There are 2 parts to this process: @@ -12,8 +11,7 @@ are 2 parts to this process: The rest of this tutorial outlines the various ways of doing all this. -Acquiring object references ---------------------------- +## Acquiring object references For all `Object`\s, the most basic way of referencing them is to get a reference to an existing object from another acquired instance. @@ -131,10 +129,7 @@ gdscript GDScript print(globals.my_getter()) ``` - - -Accessing data or logic from an object --------------------------------------- +## Accessing data or logic from an object Pandemonium's scripting API is duck-typed. This means that if a script executes an operation, Pandemonium doesn't validate that it supports the operation by **type**. diff --git a/03_usage/22_best_practices/08_pandemonium_notifications.md b/03_usage/22_best_practices/08_pandemonium_notifications.md index 65b4858..ead26de 100644 --- a/03_usage/22_best_practices/08_pandemonium_notifications.md +++ b/03_usage/22_best_practices/08_pandemonium_notifications.md @@ -1,7 +1,6 @@ -Pandemonium notifications -=================== +# Pandemonium notifications Every Object in Pandemonium implements a `notification` method. Its purpose is to @@ -70,8 +69,7 @@ Note: So, in which situation should one use each of these notifications or virtual functions? -_process vs. _physics_process vs. \*_input ------------------------------------------- +## _process vs. _physics_process vs. \*_input Use `process` when one needs a framerate-dependent deltatime between frames. If code that updates object data needs to update as often as @@ -124,8 +122,7 @@ gdscript GDScript ``` -_init vs. initialization vs. export ------------------------------------ +## _init vs. initialization vs. export If the script initializes its own node subtree, without a scene, that code should execute here. Other property or SceneTree-independent @@ -170,8 +167,7 @@ following sequence: As a result, instantiating a script versus a scene will affect both the initialization *and* the number of times the engine calls the setter. -_ready vs. _enter_tree vs. NOTIFICATION_PARENTED ------------------------------------------------- +## _ready vs. _enter_tree vs. NOTIFICATION_PARENTED When instantiating a scene connected to the first executed scene, Pandemonium will instantiate nodes down the tree (making `init` calls) and build the tree diff --git a/03_usage/22_best_practices/09_data_preferences.md b/03_usage/22_best_practices/09_data_preferences.md index 009415e..da805b5 100644 --- a/03_usage/22_best_practices/09_data_preferences.md +++ b/03_usage/22_best_practices/09_data_preferences.md @@ -1,7 +1,6 @@ -Data preferences -================ +# Data preferences Ever wondered whether one should approach problem X with data structure Y or Z? This article covers a variety of topics related to these dilemmas. @@ -37,8 +36,7 @@ Note: algorithm / data structure for the job is part of what makes programmers' skills valuable. -Array vs. Dictionary vs. Object -------------------------------- +## Array vs. Dictionary vs. Object Pandemonium stores all variables in the scripting API in the `Variant ( https://docs.pandemoniumengine.org/en/latest/development/cpp/variant_class.html )` @@ -46,7 +44,7 @@ class. Variants can store Variant-compatible data structures such as `Array` as well as `Object` s. -Pandemonium implements Array as a `Vector .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, diff --git a/03_usage/22_best_practices/12_version_control_systems.md b/03_usage/22_best_practices/12_version_control_systems.md index 9885d47..bc91851 100644 --- a/03_usage/22_best_practices/12_version_control_systems.md +++ b/03_usage/22_best_practices/12_version_control_systems.md @@ -1,10 +1,8 @@ -Version Control Systems -======================= +# Version Control Systems -Introduction ------------- +## Introduction Pandemonium aims to be VCS friendly and generate mostly readable and mergeable files. Pandemonium also supports the use of version control systems in the editor itself. @@ -13,8 +11,7 @@ VCS can be setup or shut down in the editor under **Project > Version Control**. ![](img/version_control_menu.png) -Official Git plugin -------------------- +## Official Git plugin Using Git from inside the editor is supported with an official plugin. You can find the latest releases @@ -22,8 +19,7 @@ You can find the latest releases plugin can be found `here ( https://github.com/Relintai/pandemonium_engine-git-plugin/wiki )`. -Files to exclude from VCS -------------------------- +## Files to exclude from VCS There are some folders Pandemonium creates you should have your VCS ignore: @@ -35,8 +31,7 @@ There are some folders Pandemonium creates you should have your VCS ignore: - `.mono/`: This folder stores automatically-generated Mono files. It only exists in projects that use the Mono version of Pandemonium. -Working with Git on Windows ---------------------------- +## Working with Git on Windows Most Git for Windows clients are configured with the `core.autocrlf` set to `true`. This can lead to files unnecessarily being marked as modified by Git due to their line endings being converted automatically. diff --git a/03_usage/22_best_practices/13_list_of_tricks.md b/03_usage/22_best_practices/13_list_of_tricks.md index 6f3c553..14cd5ce 100644 --- a/03_usage/22_best_practices/13_list_of_tricks.md +++ b/03_usage/22_best_practices/13_list_of_tricks.md @@ -1,8 +1,8 @@ +# Things that are not documented nor indicated anywhere + From https://github.com/godotengine/godot-docs/issues/4377 -Things that are not documented nor indicated anywhere - You can hold Shift when dragging a node in Scene Tree Dock to keep local transform If you hold Ctrl while dragging a script file onto a node in scene tree, it will be instantiated as a new node instead of attached You can drag and drop nodes (1 or more) from Scene Tree into Script Editor to insert their path diff --git a/04_modules/01_thread_pool.md b/04_modules/01_thread_pool.md index 4320427..d467c9a 100644 --- a/04_modules/01_thread_pool.md +++ b/04_modules/01_thread_pool.md @@ -1,5 +1,7 @@ # Thread pool module +Todo: was merged into core. + A c++ Pandemonium engine module, that will help you with threading. It can also work if threads are not available (like on the javascript backend), in this case it runs jobs on the @@ -8,11 +10,6 @@ is allocated per frame. You can access it's setting from the `Project->Project Settings...` menu, in the `ThreadPool` category. -# Pre-built binaries - -You can grab a pre-built editor binary from the [Broken Seals](https://github.com/Relintai/broken_seals/releases) -repo, should you want to. It contains all my modules. - # ThreadPoolJob Contains a job that can run on different threads. @@ -112,33 +109,3 @@ If you have a job, submit it using `add_job`: MyJob job = MyJob.new() ThreadPool.add_job(job) ``` - -It's api is still a bit messy, it will be cleaned up (hopefully very soon). - -# Building - -1. Get the source code for the engine. - -If you want Pandemonium 3.2: -```git clone -b 3.2 https://github.com/Relintai/pandemonium_engine.git pandemonium``` - -If you want Pandemonium 4.0: -```git clone https://github.com/Relintai/pandemonium_engine.git pandemonium``` - -[last tested commit](https://github.com/Relintai/pandemonium_engine/commit/b7e10141197fdd9b0dbc4cfa7890329510d36540) - -2. Go into Pandemonium's modules directory. - -``` -cd ./pandemonium/modules/ -``` - -3. Clone this repository - -``` -git clone https://github.com/Relintai/thread_pool thread_pool -``` - -4. Build Pandemonium. [Tutorial](https://docs.pandemoniumengine.org/en/latest/development/compiling/index.html) - - diff --git a/04_modules/02_texture_packer.md b/04_modules/02_texture_packer.md index eb762ed..4787b8e 100644 --- a/04_modules/02_texture_packer.md +++ b/04_modules/02_texture_packer.md @@ -8,39 +8,6 @@ It uses the legacy version of [rectpack2D](https://github.com/TeamHypersomnia/re It should work on all platforms. -It supports both pandemonium 3.2 and 4.0 (master [last tested commit](https://github.com/Relintai/pandemonium_engine/commit/b7e10141197fdd9b0dbc4cfa7890329510d36540)). Note that since 4.0 is still in very early stages I only -check whether it works from time to time. - -# Pre-built binaries - -You can grab a pre-built editor binary from the [Broken Seals](https://github.com/Relintai/broken_seals/releases) -repo, should you want to. It contains all my modules. - -# Building - -1. Get the source code for the engine. - -If you want Pandemonium 3.2: -```git clone -b 3.2 https://github.com/Relintai/pandemonium_engine.git pandemonium``` - -If you want Pandemonium 4.0: -```git clone https://github.com/Relintai/pandemonium_engine.git pandemonium``` - - -2. Go into Pandemonium's modules directory. - -``` -cd ./pandemonium/modules/ -``` - -3. Clone this repository - -``` -git clone https://github.com/Relintai/texture_packer texture_packer -``` - -4. Build Pandemonium. [Tutorial](https://docs.pandemoniumengine.org/en/latest/development/compiling/index.html) - # Features and Usage ## TexturePacker diff --git a/04_modules/03_mesh_utils.md b/04_modules/03_mesh_utils.md index 89f4518..82b6a61 100644 --- a/04_modules/03_mesh_utils.md +++ b/04_modules/03_mesh_utils.md @@ -2,14 +2,6 @@ This is a c++ engine module for the Pandemonium engine, containing my mesh merging utilities. -It supports both pandemonium 3.2 and 4.0 (master [last tested commit](https://github.com/Relintai/pandemonium_engine/commit/b7e10141197fdd9b0dbc4cfa7890329510d36540)). Note that since 4.0 is still in very early stages I only -check whether it works from time to time. - -# Pre-built binaries - -You can grab a pre-built editor binary from the [Broken Seals](https://github.com/Relintai/broken_seals/releases) -repo, should you want to. It contains all my modules. - # Optional Dependencies [Mesh Data Resource](https://github.com/Relintai/mesh_data_resource): Support for merged meshes, even in gles2. @@ -31,30 +23,3 @@ Porting is mostly done, but it does needs some debugging (it has a crash if smar I might just return to using the original FQMS. As if meshes are merged together using `MeshUtils.merge_mesh_array`, or `bake_mesh_array_uv` the original algorithm will work fine. Still on the fence about it. - -# Building - -1. Get the source code for the engine. - -If you want Pandemonium 3.2: -```git clone -b 3.2 https://github.com/Relintai/pandemonium_engine.git pandemonium``` - -If you want Pandemonium 4.0: -```git clone https://github.com/Relintai/pandemonium_engine.git pandemonium``` - - -2. Go into Pandemonium's modules directory. - -``` -cd ./pandemonium/modules/ -``` - -3. Clone this repository - -``` -git clone https://github.com/Relintai/mesh_utils mesh_utils -``` - -4. Build Pandemonium. [Tutorial](https://docs.pandemoniumengine.org/en/latest/development/compiling/index.html) - - diff --git a/04_modules/04_mesh_data_resource.md b/04_modules/04_mesh_data_resource.md index 892bd19..cb63264 100644 --- a/04_modules/04_mesh_data_resource.md +++ b/04_modules/04_mesh_data_resource.md @@ -9,11 +9,6 @@ The module also comes with importers (gltf, and collada for now), you can import `https://github.com/Relintai/props`: If present, you also get a prop importer for MeshDataInstances. `https://github.com/Relintai/mesh_utils`: If present, you get mesh simplification/optimization options at import. -## Pre-built binaries - -You can grab a pre-built editor binary from the [Broken Seals](https://github.com/Relintai/broken_seals/releases) -repo, should you want to. It contains all my modules. - ## MeshDataResource The resource that holds mesh and collider data. @@ -39,31 +34,3 @@ if you set it to multiple, you get a MeshDataResourceCollection as the main reso Since MeshDataResource can hold collider information, these importers can create this for you. There are quite a few options for it: ![Colliders](screenshots/import_2.png) - -## Building - -1. Get the source code for the engine. - -If you want Pandemonium 3.2: -```git clone -b 3.2 https://github.com/Relintai/pandemonium_engine.git pandemonium``` - -If you want Pandemonium 4.0: -```git clone https://github.com/Relintai/pandemonium_engine.git pandemonium``` - -[last tested commit for 4.0](https://github.com/Relintai/pandemonium_engine/commit/b7e10141197fdd9b0dbc4cfa7890329510d36540) - -2. Go into Pandemonium's modules directory. - -``` -cd ./pandemonium/modules/ -``` - -3. Clone this repository - -``` -git clone https://github.com/Relintai/mesh_data_resource mesh_data_resource -``` - -4. Build Pandemonium. [Tutorial](https://docs.pandemoniumengine.org/en/latest/development/compiling/index.html) - - diff --git a/04_modules/05_props.md b/04_modules/05_props.md index b00bb14..ad66207 100644 --- a/04_modules/05_props.md +++ b/04_modules/05_props.md @@ -4,14 +4,6 @@ This is a c++ engine module for the Pandemonium Engine. It gives you props, and editor utilities to convert scenes to props. -It supports both pandemonium 3.2 and 4.0 (master [last tested commit](https://github.com/Relintai/pandemonium_engine/commit/b7e10141197fdd9b0dbc4cfa7890329510d36540)). Note that since 4.0 is still in very early stages I only -check whether it works from time to time. - -# Pre-built binaries - -You can grab a pre-built editor binary from the [Broken Seals](https://github.com/Relintai/broken_seals/releases) -repo, should you want to. It contains all my modules. - # Optional Dependencies [Mesh Data Resource](https://github.com/Relintai/mesh_data_resource): Support for merged meshes, even in gles2.\ @@ -67,29 +59,3 @@ You can register new PropDataEntries as processors, should you need to. You can either click the new "To Prop" button on the menubar of the 3D scene for a quick conversion, or look into Project->Tools. -# Building - -1. Get the source code for the engine. - -If you want Pandemonium 3.2: -```git clone -b 3.2 https://github.com/Relintai/pandemonium_engine.git pandemonium``` - -If you want Pandemonium 4.0: -```git clone https://github.com/Relintai/pandemonium_engine.git pandemonium``` - - -2. Go into Pandemonium's modules directory. - -``` -cd ./pandemonium/modules/ -``` - -3. Clone this repository - -``` -git clone https://github.com/Relintai/props props -``` - -4. Build Pandemonium. [Tutorial](https://docs.pandemoniumengine.org/en/latest/development/compiling/index.html) - - diff --git a/04_modules/06_props_2d.md b/04_modules/06_props_2d.md index 797461e..23f099e 100644 --- a/04_modules/06_props_2d.md +++ b/04_modules/06_props_2d.md @@ -4,14 +4,6 @@ This is a c++ engine module for the Pandemonium Engine. It gives you props, and editor utilities to convert scenes to props. -It supports both pandemonium 3.2 and 4.0 (master [last tested commit](https://github.com/Relintai/pandemonium_engine/commit/b7e10141197fdd9b0dbc4cfa7890329510d36540)). Note that since 4.0 is still in very early stages I only -check whether it works from time to time. - -# Pre-built binaries - -You can grab a pre-built editor binary from the [Broken Seals](https://github.com/Relintai/broken_seals/releases) -repo, should you want to. It contains all my modules. - # Optional Dependencies [Mesh Data Resource](https://github.com/Relintai/mesh_data_resource): Support for merged meshes, even in gles2.\ @@ -67,29 +59,3 @@ You can register new Prop2DDataEntries as processors, should you need to. You can either click the new "To Prop2D" button on the menubar of the 3D scene for a quick conversion, or look into Project->Tools. -# Building - -1. Get the source code for the engine. - -If you want Pandemonium 3.2: -```git clone -b 3.2 https://github.com/Relintai/pandemonium_engine.git pandemonium``` - -If you want Pandemonium 4.0: -```git clone https://github.com/Relintai/pandemonium_engine.git pandemonium``` - - -2. Go into Pandemonium's modules directory. - -``` -cd ./pandemonium/modules/ -``` - -3. Clone this repository - -``` -git clone https://github.com/Relintai/props props -``` - -4. Build Pandemonium. [Tutorial](https://docs.pandemoniumengine.org/en/latest/development/compiling/index.html) - - diff --git a/04_modules/07_terraman.md b/04_modules/07_terraman.md index b429cc0..b6578cf 100644 --- a/04_modules/07_terraman.md +++ b/04_modules/07_terraman.md @@ -12,14 +12,6 @@ This is an engine module! Which means that you will need to compile it into Pand You can grab pre-built binaries (even editor + export templates) from the [Broken Seals](https://github.com/Relintai/broken_seals/releases) repo. -## Pandemonium Version Support - -3.2 - Will likely work, probably needs changes by now. (TODO check.)\ -3.3 - Will more likely work, might need smaller changes by now. (TODO check.)\ -3.4 - Should work without any issues. (TODO check.)\ -3.x - Works.\ -4.0 - Have been fixing support from time to time. Currently it won't build. Mostly done with the fix though. - ## Optional Dependencies `https://github.com/Relintai/texture_packer`: You get access to [TerraLibraryMerger](#voxellibrarymerger) and [TerraLibraryMergerPCM](#voxellibrarymergerpcm). \ @@ -179,42 +171,3 @@ If you want to implement your own meshing algorithm you can do so by overriding TerraMesher works similarly to SurfaceTool, so first you need to set colors, uvs, etc and then call add_vertex. They won't get reset, so for example if you want all your vertices to have a certain color, you can get away with setting it only once. - -## Compiling - -First make sure that you can compile pandemonium. See the official docs: https://docs.pandemoniumengine.org/en/3.x/development/compiling/index.html - -1. Clone the engine if you haven't already: - -If you want Pandemonium 3.x: -```git clone -b 3.x https://github.com/Relintai/pandemonium_engine.git pandemonium``` - -If you want Pandemonium 4.0: -```git clone https://github.com/Relintai/pandemonium_engine.git pandemonium``` - - -2. go into the modules folder inside the engine's directory: - -```cd pandemonium``` \ -```cd modules``` - -3. clone this repository - -```git clone https://github.com/Relintai/terraman.git terraman``` - -(the folder needs to be named terraman!) - -4. If you want the optional dependencies run these commands as well: - -```git clone https://github.com/Relintai/texture_packer.git texture_packer``` \ -```git clone https://github.com/Relintai/mesh_data_resource.git mesh_data_resource``` - -5. Go up one folder - -```cd ..``` - -6. Compile pandemonium. - -For example: - -```scons p=x11 t=release_debug tools=yes``` diff --git a/04_modules/08_terraman_2d.md b/04_modules/08_terraman_2d.md index 0b46b49..efdd65d 100644 --- a/04_modules/08_terraman_2d.md +++ b/04_modules/08_terraman_2d.md @@ -8,18 +8,6 @@ I could have technically implemented all of this into voxelman, as having only h So I ended up creating this. Everything works the same as in voxelman, but the apis have been simplified to make UX a bit better. -This is an engine module! Which means that you will need to compile it into Pandemonium! [See the compiling section here.](#compiling) - -You can grab pre-built binaries (even editor + export templates) from the [Broken Seals](https://github.com/Relintai/broken_seals/releases) repo. - -## Pandemonium Version Support - -3.2 - Will likely work, probably needs changes by now. (TODO check.)\ -3.3 - Will more likely work, might need smaller changes by now. (TODO check.)\ -3.4 - Should work without any issues. (TODO check.)\ -3.x - Works.\ -4.0 - Have been fixing support from time to time. Currently it won't build. Mostly done with the fix though. - ## Optional Dependencies `https://github.com/Relintai/thread_pool`: Threaded chunk generation. Without this terraman is single threaded! \ @@ -181,42 +169,3 @@ If you want to implement your own meshing algorithm you can do so by overriding TerraMesher works similarly to SurfaceTool, so first you need to set colors, uvs, etc and then call add_vertex. They won't get reset, so for example if you want all your vertices to have a certain color, you can get away with setting it only once. - -## Compiling - -First make sure that you can compile pandemonium. See the official docs: https://docs.pandemoniumengine.org/en/3.x/development/compiling/index.html - -1. Clone the engine if you haven't already: - -If you want Pandemonium 3.x: -```git clone -b 3.x https://github.com/Relintai/pandemonium_engine.git pandemonium``` - -If you want Pandemonium 4.0: -```git clone https://github.com/Relintai/pandemonium_engine.git pandemonium``` - - -2. go into the modules folder inside the engine's directory: - -```cd pandemonium``` \ -```cd modules``` - -3. clone this repository - -```git clone https://github.com/Relintai/terraman.git terraman``` - -(the folder needs to be named terraman!) - -4. If you want the optional dependencies run these commands as well: - -```git clone https://github.com/Relintai/texture_packer.git texture_packer``` \ -```git clone https://github.com/Relintai/mesh_data_resource.git mesh_data_resource``` - -5. Go up one folder - -```cd ..``` - -6. Compile pandemonium. - -For example: - -```scons p=x11 t=release_debug tools=yes``` diff --git a/04_modules/09_voxelman.md b/04_modules/09_voxelman.md index f75a2e0..8ef05b5 100644 --- a/04_modules/09_voxelman.md +++ b/04_modules/09_voxelman.md @@ -6,17 +6,6 @@ This is an engine module! Which means that you will need to compile it into Pand You can find a demonstration project (with pre-built binaries) here: https://github.com/Relintai/the_tower -## Pandemonium Version Support - -I'm currently mostly using [Terraman](https://github.com/Relintai/terraman) instead of this, so it might get temporarily a bit behind.\ -If compile breaks, and I don't notice please report. - -3.2 - Will likely work, probably needs changes by now. (TODO check.)\ -3.3 - Will more likely work, might need smaller changes by now. (TODO check.)\ -3.4 - Should work without any issues. (TODO check.)\ -3.x - Works. [last tested commit](6ea58db2d849d9ca0ccee5bc6a6d2b919d404bc1)\ -4.0 - Have been fixing support from time to time. Currently it won't build. Mostly done with the fix though. - ## Optional Dependencies `https://github.com/Relintai/texture_packer`: You get access to [VoxelLibraryMerger](#voxellibrarymerger) and [VoxelLibraryMergerPCM](#voxellibrarymergerpcm). \ @@ -186,42 +175,3 @@ If you want to implement your own meshing algorithm you can do so by overriding VoxelMesher works similarly to SurfaceTool, so first you need to set colors, uvs, etc and then call add_vertex. They won't get reset, so for example if you want all your vertices to have a certain color, you can get away with setting it only once. - -## Compiling - -First make sure that you can compile pandemonium. See the official docs: https://docs.pandemoniumengine.org/en/3.x/development/compiling/index.html - -1. Clone the engine if you haven't already: - -If you want Pandemonium 3.x: -```git clone -b 3.x https://github.com/Relintai/pandemonium_engine.git pandemonium``` - -If you want Pandemonium 4.0: -```git clone https://github.com/Relintai/pandemonium_engine.git pandemonium``` - - -2. go into the modules folder inside the engine's directory: - -```cd pandemonium``` \ -```cd modules``` - -3. clone this repository - -```git clone https://github.com/Relintai/voxelman.git voxelman``` - -(the folder needs to be named voxelman!) - -4. If you want the optional dependencies run these commands as well: - -```git clone https://github.com/Relintai/texture_packer.git texture_packer``` \ -```git clone https://github.com/Relintai/mesh_data_resource.git mesh_data_resource``` - -5. Go up one folder - -```cd ..``` - -6. Compile pandemonium. - -For example: - -```scons p=x11 t=release_debug tools=yes``` diff --git a/04_modules/10_entity_spell_system.md b/04_modules/10_entity_spell_system.md index 163af64..a56947a 100644 --- a/04_modules/10_entity_spell_system.md +++ b/04_modules/10_entity_spell_system.md @@ -6,18 +6,6 @@ vendors, interaction, targeting, equipment (+ visuals), loot, crafting, talents, The module supports networking. It is designed to be authoritative, so players shouldn't be able to cheat by design. -It is a c++ engine module, which means you will need to compile it into pandemonium. (See compiling) - -## Pandemonium Version Support - -This module is developed with the 3.x branch of pandemonium, usually at the newest revisions. - -3.2 - Will likely work, probably needs changes by now. (TODO check.)\ -3.3 - Will more likely work, might need smaller changes by now. (TODO check.)\ -3.4 - Should work without any issues. (TODO check.)\ -3.x - Works.\ -4.0 - Have been fixing support from time to time. Currently it won't build on the latest master, and it will take considerable amount of work to get it to work again after the virtual method binding rework. It will be done eventually, but it will take time. [Here](https://github.com/Relintai/pandemonium_engine/commit/b7e10141197fdd9b0dbc4cfa7890329510d36540)'s the last know-to-work commit. - ## Project setup tl;dr ### First @@ -565,36 +553,3 @@ https://github.com/Relintai/broken_seals_roguelike 2d: https://github.com/Relintai/broken_seals_2d.git - -## Compiling - -First make sure that you can compile pandemonium. See the official docs: https://docs.pandemoniumengine.org/en/3.x/development/compiling/index.html - -1. Clone the engine if you haven't already: - -If you want Pandemonium 3.x: -```git clone -b 3.x https://github.com/Relintai/pandemonium_engine.git pandemonium``` - -If you want Pandemonium 4.0: -```git clone https://github.com/Relintai/pandemonium_engine.git pandemonium``` - -2. go into the modules folder inside the engine's directory" - -```cd pandemonium``` -```cd modules``` - -3. clone this repository - -```git clone https://github.com/Relintai/entity_spell_system.git entity_spell_system``` - -(the folder needs to be named entity_spell_system!) - -4. Go up one folder - -```cd ..``` - -5. Compile pandemonium. - -For example: - -```scons p=x11 t=release_debug tools=yes``` diff --git a/04_modules/11_skeleton_editor.md b/04_modules/11_skeleton_editor.md index 32add1d..8f2f195 100644 --- a/04_modules/11_skeleton_editor.md +++ b/04_modules/11_skeleton_editor.md @@ -5,24 +5,3 @@ This is a c++ engine module for the Pandemonium engine that contains a modulariz The original pr is here: https://github.com/Relintai/pandemonium_engine/pull/45699 Tht 3.x version (linked in the pr itself) is here (This is the base for this module): https://github.com/TokageItLab/pandemonium/tree/pose-edit-mode -I'm developing this for pandemonium 3.x, it will probably work on earlier versions though. 4.0 is not supported. - -# Building - -1. Get the source code for the engine. - -```git clone -b 3.x https://github.com/Relintai/pandemonium_engine.git pandemonium``` - -2. Go into Pandemonium's modules directory. - -``` -cd ./pandemonium/modules/ -``` - -3. Clone this repository - -``` -git clone https://github.com/Relintai/skeleton_editor skeleton_editor -``` - -4. Build Pandemonium. [Tutorial](https://docs.pandemoniumengine.org/en/latest/development/compiling/index.html) diff --git a/04_modules/12_ui_extensions.md b/04_modules/12_ui_extensions.md index 6c8f46f..1a82560 100644 --- a/04_modules/12_ui_extensions.md +++ b/04_modules/12_ui_extensions.md @@ -2,14 +2,6 @@ This is a c++ engine module for the Pandemonium engine, containing smaller utilities. -It supports both pandemonium 3.2 and 4.0 (master [last tested commit](https://github.com/Relintai/pandemonium_engine/commit/b7e10141197fdd9b0dbc4cfa7890329510d36540)). Note that since 4.0 is still in very early stages I only -check whether it works from time to time. - -# Pre-built binaries - -You can grab a pre-built editor binary from the [Broken Seals](https://github.com/Relintai/broken_seals/releases) -repo, should you want to. It contains all my modules. - # TouchButton A `Control` based button, that handles multitouch properly. @@ -49,30 +41,5 @@ func _ready(): I recommend putting this code into a singleton. -# Building - -1. Get the source code for the engine. - -If you want Pandemonium 3.2: -```git clone -b 3.2 https://github.com/Relintai/pandemonium_engine.git pandemonium``` - -If you want Pandemonium 4.0: -```git clone https://github.com/Relintai/pandemonium_engine.git pandemonium``` - - -2. Go into Pandemonium's modules directory. - -``` -cd ./pandemonium/modules/ -``` - -3. Clone this repository - -``` -git clone https://github.com/Relintai/ui_extensions ui_extensions -``` - -4. Build Pandemonium. [Tutorial](https://docs.pandemoniumengine.org/en/latest/development/compiling/index.html) - diff --git a/03_usage/02_2d/img/autotile_template_2x2.png b/04_modules/layered_tile_maps/img/autotile_template_2x2.png similarity index 100% rename from 03_usage/02_2d/img/autotile_template_2x2.png rename to 04_modules/layered_tile_maps/img/autotile_template_2x2.png diff --git a/03_usage/02_2d/img/autotile_template_3x3_minimal.png b/04_modules/layered_tile_maps/img/autotile_template_3x3_minimal.png similarity index 100% rename from 03_usage/02_2d/img/autotile_template_3x3_minimal.png rename to 04_modules/layered_tile_maps/img/autotile_template_3x3_minimal.png diff --git a/03_usage/02_2d/img/autotile_template_3x3_minimal_16.png b/04_modules/layered_tile_maps/img/autotile_template_3x3_minimal_16.png similarity index 100% rename from 03_usage/02_2d/img/autotile_template_3x3_minimal_16.png rename to 04_modules/layered_tile_maps/img/autotile_template_3x3_minimal_16.png diff --git a/03_usage/02_2d/img/autotile_template_3x3_minimal_topdown_floor.png b/04_modules/layered_tile_maps/img/autotile_template_3x3_minimal_topdown_floor.png similarity index 100% rename from 03_usage/02_2d/img/autotile_template_3x3_minimal_topdown_floor.png rename to 04_modules/layered_tile_maps/img/autotile_template_3x3_minimal_topdown_floor.png diff --git a/03_usage/02_2d/img/autotile_template_3x3_minimal_topdown_walls.png b/04_modules/layered_tile_maps/img/autotile_template_3x3_minimal_topdown_walls.png similarity index 100% rename from 03_usage/02_2d/img/autotile_template_3x3_minimal_topdown_walls.png rename to 04_modules/layered_tile_maps/img/autotile_template_3x3_minimal_topdown_walls.png diff --git a/03_usage/02_2d/img/autotile_template_3x3_minimal_topdown_walls_tall.png b/04_modules/layered_tile_maps/img/autotile_template_3x3_minimal_topdown_walls_tall.png similarity index 100% rename from 03_usage/02_2d/img/autotile_template_3x3_minimal_topdown_walls_tall.png rename to 04_modules/layered_tile_maps/img/autotile_template_3x3_minimal_topdown_walls_tall.png diff --git a/03_usage/02_2d/img/autotile_template_3x3_minimal_topdown_walls_thick.png b/04_modules/layered_tile_maps/img/autotile_template_3x3_minimal_topdown_walls_thick.png similarity index 100% rename from 03_usage/02_2d/img/autotile_template_3x3_minimal_topdown_walls_thick.png rename to 04_modules/layered_tile_maps/img/autotile_template_3x3_minimal_topdown_walls_thick.png diff --git a/04_modules/tile_maps/01_using_tilemaps.md b/04_modules/tile_maps/01_using_tilemaps.md index adc5f1e..c31e338 100644 --- a/04_modules/tile_maps/01_using_tilemaps.md +++ b/04_modules/tile_maps/01_using_tilemaps.md @@ -1,10 +1,7 @@ +# Using TileMaps -Using TileMaps -============== - -Introduction ------------- +## Introduction A tilemap is a grid of tiles used to create a game's layout. There are several benefits to using `TileMap` nodes to design your levels. @@ -17,8 +14,7 @@ the TileMap. ![](img/tileset_draw_atlas.png) -Project setup -------------- +## Project setup This demo will use the following tiles taken from Kenney's "Abstract Platformer" art pack. You can find the complete set `here ( https://kenney.nl/assets/abstract-platformer )` @@ -33,8 +29,7 @@ is to import 2D images using an interpolated "filter" mode, which will result in ugly borders between the tiles. Select the image and click the Import tab. Turn off `Filter` and click "Reimport". See `doc_import_images` for details. -TileMap node ------------- +## TileMap node Add a new `TileMap` node to the scene. By default, a TileMap uses a square grid of tiles. You can also use a perspective-based "Isometric" mode @@ -67,8 +62,7 @@ customize your tilemap's behavior: All of these options can be left at their defaults for this demo. -Creating a TileSet ------------------- +## Creating a TileSet Once you've configured your tilemap, it's time to add a `TileSet`. A TileSet is a @@ -106,8 +100,7 @@ the node's lock button: ![](img/tile_lock.png) -Collision shapes ----------------- +## Collision shapes If you're making a map that needs collisions - walls, floor, or other obstacles, for example - then you'll need to add collision shapes to any tiles that you @@ -123,8 +116,7 @@ collision shape appears in light blue: You can add occlusion and navigation shapes to the tile in the same way. -Atlas tiles ------------ +## Atlas tiles Rather than adding individual tiles one at a time, you can define a group of tiles all at once using an atlas. This also allows you to randomly generate @@ -152,8 +144,7 @@ tiles it contains: In addition to saving time when defining the tiles, this can help by grouping similar tiles together when you're working with a large number of tiles. -Random tile priorities -~~~~~~~~~~~~~~~~~~~~~~ +### Random tile priorities When drawing with atlas tiles, enabling the "Use priority" option causes tiles to be selected at random. By default, each tile in the tileset has an equal @@ -162,8 +153,7 @@ priorities for each tile. For example, a tile with priority 2 is twice as likely to be selected as a tile with priority 1, and a tile with priority 3 is 50% more likely to be selected than a tile with priority 2. -Autotiles ---------- +## Autotiles Autotiles allow you to define a group of tiles, then add rules to control which tile gets used for drawing based on the content of adjacent cells. @@ -191,8 +181,7 @@ heading. Allowed values are "2x2", "3x3 (minimal)", and "3x3". All "on" and "off" bits must be satisfied for a bitmask to match, but "ignore" bits are ignored. -2x2 -~~~ +### 2x2 In 2x2 mode, each bitmask contains four bits, one for each corner. @@ -223,8 +212,7 @@ Key: ![](img/autotile_template_2x2.png) -3x3 (minimal) -~~~~~~~~~~~~~ +### 3x3 (minimal) In 3x3 (minimal) mode, each bitmask contains 9 bits (4 corners, 4 edges, 1 center). The 4 corner bits work the same as in 2x2 mode. @@ -241,7 +229,6 @@ arrangement that this mode can test for. Note: - Right-click an image and choose **Save image as…** to save it. **Template - Generic:** @@ -302,8 +289,7 @@ This means the texture offset should be `Vector2(0, -120)`: ![](img/autotile_template_3x3_minimal_topdown_walls_tall.png) -3x3 -~~~ +### 3x3 In 3x3 mode, each bitmask contains 9 bits (4 corners, 4 edges, 1 center) @@ -314,15 +300,13 @@ A total of 256 tiles would be needed to provide exactly one bitmask for each arrangement that this mode can test for. -Disabling autotile -~~~~~~~~~~~~~~~~~~ +### Disabling autotile When using an autotile, it is possible to turn off the autotile behaviour and select tiles manually, by clicking "Disable Autotile" at the top of the tile selection window. -Autotile binding -~~~~~~~~~~~~~~~~ +### Autotile binding By default, autotile only checks for adjacent cells filled using the same autotile. This behaviour can be overridden in order to have autotiles bind to @@ -338,8 +322,7 @@ Note that to use this in the editor, the script should start with a "tool" declaration, and you may need to close and reload the scene for these changes to take effect. -Tips and tricks ---------------- +## Tips and tricks - If you're using a `Camera2D` to scroll your level, you may notice lines appearing between your tiles. To fix this, open Project diff --git a/04_modules/tile_maps/img/autotile_template_2x2.png b/04_modules/tile_maps/img/autotile_template_2x2.png new file mode 100644 index 0000000000000000000000000000000000000000..17b4bc7b475153e7a7cae69b83975a5fc1aad842 GIT binary patch literal 226 zcmeAS@N?(olHy`uVBq!ia0y~yU<5K58JL)Xl%kBoS0Ke1;1lAy-SYo`%dG$Z|LEaktaqI03U%n;-0k#0WhpIOHMaJ(OY?g8_%FunuuM$vmKkw4aZT(kzW3N}O z>tElq^y|}qUi0nk_q6AoeqH&S5ok05tYKNYWw%n8Y zuu+cH=QXO#R)(9_$7`KF{%flP1p@+{W!kpS;gwVAXM_-#<;(o6C$#h$`wQ;h%dNJ` zqsThwI($2KasGv(yC?EdBp%#oSjD^i-yi13rYPbJ2jZEZiTqzHlsCiFo~2>UzaRfl d<+nCm`^;j!{++Px$*y%EDNk2Fmvv4FO#nSWgXsVO literal 0 HcmV?d00001 diff --git a/04_modules/tile_maps/img/autotile_template_3x3_minimal_16.png b/04_modules/tile_maps/img/autotile_template_3x3_minimal_16.png new file mode 100644 index 0000000000000000000000000000000000000000..64209ae358b9dbb9a157e5e35243fad18541caf0 GIT binary patch literal 1312 zcmeAS@N?(olHy`uVBq!ia0y~yU<5K5893O0R7}x|G!U;i$lZxy-8q?;3=Ax{JY5_^ zD(1YstC%P4E79=qr2gg$pZ>EwG(4+W)uy#zNjrz;DaoqN8NV3zI#wq31W%Zo`x4TxK+adPz&z@hC zmiK2b{BH2SCwt@nbN|17{J!e-ta|(X_38{9!Z=W|_6NT!`A65{w-xA`O3@1abvrVO zUanrT{A0=0TeJ5)ike?9gvV%HRzk#!)gSoXv8{{#^X5_g(%L;STfcoOoqqrR_K@0t zk#iUnd~l;Ps}ERj{9$^<@Yvn{`0jbX?d)Q=e!Enf{zv-luRohD7;#4CjkBl!zP^2J zHp8}u!02f=JXT?Gf8Fj^J=qh_pI@zC`D=$*760e+JH&p!{}V4?zkb)cpWi?KE@#4> z^0qU*cljH32fwYL)D_BN;jB7j97h$Aa6vcn#eE&Vy^s8FLPEG92Pd?)g}-?{1a+Y>V0$ z?%cZ1;&c1N)fqJKM=CB^YoExkKT`jio|V{kzot*{jdn0~3%hxrV-Z_VnM^+}FMgw|_9F_}rgk UBB9?8EbNX4zUcTVRXHsE2nz%X~g3$}Mme{(0ivk&&y z3OH;g>dp1|*T+*GQ~vP$6ngndGwAWBuX`o0U;O#~`O_D7>zAHAeedJmXY4?Ou>f`E z8EJ<42D-;zAKxOm`X|SNt^aJ~8Shx_yZ(z2i*igM2~LCjfZxZLZDp5us@!nx*Vdnb zuUE&~BPn!eI&tp0p22HYkngd9dWIN<`O*xV7;_wNe_j0NcB=8b8XRgDa6Y)!d}i-! zcZRipz5lNGAJ<@nY!x=sp<;5J3RMh&btQkRzuxB#IEG|?fl9;0pYH4$k1z9OU^n2v zMuZEKe@*|j4@b~kU@`c$;M-n?Z*naCpHlx~Hw;}=hI7Gn<`ZlZq5HQXdu1krcH!Re zedZTl{8GJdg)D<)fCXm*_mg5~2eSs<6}jBEW`E~Jl0+~Mcrq@FJfm)*d;GoQo9NF= z|J`f8cabTZe-ctCAXHo zBn7r4?F1<-3GxeOaCmkjje&t_fv1aONX4xr1GxYLE(xEQ4@~J%r=_`)n4)g>AJs~9 zs4j1abmVDa-0?;2Hh0K(j=lfqaxHbdwSS|v+Z%I-zjL2Ft$oA1Ir8QDA2mRup+HUg z3A4|>12fbcHtx4tZxMg0943QF_sy^RE%C48XUgBN|7s3QJ>$l{5xg;{y&lH>p)=x0k`6BgzTw1{7+KhD?$(^38iHjzBb?b&D`_c zn_;CqnjCg+gIGh`9{z;A^_x8_v8%{nD5!7v%{;|D;NxrtwVn47s=l)?`PU_b;G?o$ zuvqNN{?i`$@3z9X`p?lgFJ1-$>{?W>l3g5qeWz1oo@S72v zstbG%{xN)K*XUpH%(E7uKvzG<>+jW{IKzpd;hW>zsgAE#|5k6l~)y<_P2+DoM2;bDap zAEOyRaZT7HIO|KuO&Q+5-Ur!~Hcr04{75u-ukz%HrhYZ0KmUEpIJV91?1cqW)`qRE zdFTJF>fO)liMy80ub=TQ_uj9k_t&?C@q+APaA08IU|?WmP+(vv$!t&*U75IR_v(da z<#N4M-_L)}Fe(2VbU)r{H7i2{0}GmZ7N8h|0Gi;lfB$R#1l<4i?|U&*T_D16kYca_ z2|lvf@9!Uvn&-aCcK*HkcfYRGN(LL>*RPMS{-65HuR+@btO?a=Sgpb$jR+`@a5tzum5Z z;ZGY{C@lC?yM}jV^4q`sv!B0P*LLUU_xH1wKc609I`w?*+X+?c_SV>351a4*{afh? z-QD%ob(^Nozn33hty`${Q<(=TKET#WWPeXxb9V0YYmxW$*2k|}SQhTIPJw}GLmX<* zV#EVj^9g&8D|7yHXf`EIl5UG4m@QtSf*6^vhv^F`S*TaI^Q3)`PeV636r!r zutY2(5YU~7o&;bj8S=Jm^>~}*zkPR<&Yhj#>z4A-)clo+?eAZY^FAS;h?M;o#Iu5u z?H}WR`#pLu-<@uFb;k3*r(Zt5`@C}Tw_hgl@<2&g5rz^4=z>vv2_CLl-}t3WpIuy0 z{@wtm zp8CCi>gyl-)@|GB4h%Z7&3^{;dxNi5(Cn9>Vrl2+j4QkA=eaLl`aOT`|5%)H^6uwV mgS(f`%P-plNLA%BKwtX^6jRp8os@gSUy#Ojk#dfm-l)XcQbzR*l>;tq%l=+iZUkI z$9=e0#~?Ac|Ld>9#S_oEH`M&!SBs=!p5TJr^WzI@?2*KfnHua7QQoG^D`s;_wR_9n zU&sIU?-Tv=tG+$|8~=KT)gfHY&iU{Dbkbkm=g%2#+8`On%kY+w@A2=|=h=}2@h}g3 zQ`r8TrQ`c)hE0{Yls({QuwtJ3TUf_zjy>0evq%B*VFLs2-@1m4KY0{pW4ExulVRGm zAck41H9gg+&TLeNqHHe;3td}Kaa z$CI&R`+h?Wy`2v#CfwQkJK26FcE^EC$l>VmW1c?wC&vb}g~@M`gYqwf`Rkag`X0Bk zJwHj$!exSY_R2Jduag&id@rD-5+kGao7JjZ!^ZFb*pZXc0$Wdg<{Q8N luq1p3>QBL;f5Vn(zu0(;t1qAYeP9Jhji;-h%Q~loCIA=45TpPA literal 0 HcmV?d00001 diff --git a/05_engine_development/01_compiling/02_introduction_to_the_buildsystem.md b/05_engine_development/01_compiling/02_introduction_to_the_buildsystem.md index 736579e..cda7808 100644 --- a/05_engine_development/01_compiling/02_introduction_to_the_buildsystem.md +++ b/05_engine_development/01_compiling/02_introduction_to_the_buildsystem.md @@ -66,7 +66,7 @@ To list the available target platforms, use `scons platform=list`: windows x11 - Please run SCons again and select a valid platform: platform= + Please run SCons again and select a valid platform: platform=<string> ``` To build for a platform (for example, x11), run with the `platform=` (or @@ -77,7 +77,7 @@ To build for a platform (for example, x11), run with the `platform=` (or ``` This will start the build process, which will take a while. If you want -SCons to build faster, use the `-j .[opt].[tools/debug].[extension] + pandemonium.<platform>.[opt].[tools/debug].<architecture>[extension] ``` For the previous build attempt, the result would look like this: @@ -132,7 +132,7 @@ run projects but that does not include the editor or the project manager. ``` - scons platform= tools=yes/no + scons platform=<platform> tools=yes/no ``` ## Target @@ -150,7 +150,7 @@ Target controls optimization and debug flags. Each mode means: checks to run. ``` - scons platform= target=debug/release_debug/release + scons platform=<platform> target=debug/release_debug/release ``` This flag appends the `.debug` suffix (for debug), or `.tools` (for debug @@ -168,7 +168,7 @@ else. - **default**: Build for the architecture that matches the host platform. ``` - scons platform= bits=default/32/64 + scons platform=<platform> bits=default/32/64 ``` This flag appends `.32` or `.64` suffixes to resulting binaries when @@ -207,7 +207,7 @@ See also: ## Cleaning generated files Sometimes, you may encounter an error due to generated files being present. You -can remove them by using `scons --clean scons platform=uwp ``` -Creating UWP export templates ------------------------------ +## Creating UWP export templates To export using the editor you need to properly build package the templates. You need all three architectures with `debug` and `release` templates to @@ -103,8 +100,7 @@ the export templates for - e.g. `3.0.alpha` for the alpha version of Pandemonium If you don't want to replace the templates, you can set the "Custom Package" property in the export window. -Running UWP apps with Visual Studio ------------------------------------ +## Running UWP apps with Visual Studio If you want to debug the UWP port or simply run your apps without packaging and signing, you can deploy and launch them using Visual Studio. It might be diff --git a/05_engine_development/01_compiling/11_optimizing_for_size.md b/05_engine_development/01_compiling/11_optimizing_for_size.md index 244acee..5e919c9 100644 --- a/05_engine_development/01_compiling/11_optimizing_for_size.md +++ b/05_engine_development/01_compiling/11_optimizing_for_size.md @@ -1,7 +1,6 @@ # Optimizing a build for size - ## Rationale Sometimes, it is desired to optimize a build for size rather than speed. diff --git a/05_engine_development/02_cpp/01_introduction_to_pandemonium_development.md b/05_engine_development/02_cpp/01_introduction_to_pandemonium_development.md index eb22d34..c6916d2 100644 --- a/05_engine_development/02_cpp/01_introduction_to_pandemonium_development.md +++ b/05_engine_development/02_cpp/01_introduction_to_pandemonium_development.md @@ -1,23 +1,20 @@ -Introduction to Pandemonium development -================================= +# Introduction to Pandemonium development This page is meant to introduce the global organization of Pandemonium Engine's source code, and give useful tips for extending/fixing the engine on the C++ side. -Architecture diagram --------------------- +## Architecture diagram The following diagram describes the architecture used by Pandemonium, from the core components down to the abstracted drivers, via the scene structure and the servers. -![](img/architecture_diagram.jpg +![](img/architecture_diagram.jpg) -Debugging the editor with gdb ------------------------------ +## Debugging the editor with gdb If you are writing or correcting bugs affecting Pandemonium Engine's editor, remember that the binary will by default run the project manager first, diff --git a/05_engine_development/02_cpp/02_common_engine_methods_and_macros.md b/05_engine_development/02_cpp/02_common_engine_methods_and_macros.md index 7b3c7d1..2613d89 100644 --- a/05_engine_development/02_cpp/02_common_engine_methods_and_macros.md +++ b/05_engine_development/02_cpp/02_common_engine_methods_and_macros.md @@ -1,14 +1,13 @@ -Common engine methods and macros -================================ +# Common engine methods and macros Pandemonium's C++ codebase makes use of dozens of custom methods and macros which are used in almost every file. This page is geared towards beginner contributors, but it can also be useful for those writing custom C++ modules. -Print text ----------- +## Print text + ``` // Prints a message to standard output. @@ -31,8 +30,7 @@ Print text If you need to add placeholders in your messages, use format strings as described below. -Format a string ---------------- +## Format a string The `vformat()` function returns a formatted `String`. It behaves in a way similar to C's `sprintf()`: @@ -51,8 +49,7 @@ in a way similar to C's `sprintf()`: In most cases, try to use `vformat()` instead of string concatenation as it makes for more readable code. -Convert an integer or float to a string ---------------------------------------- +## Convert an integer or float to a string This is mainly useful when printing numbers directly. @@ -64,8 +61,7 @@ This is mainly useful when printing numbers directly. print_line(rtos(123.45)); ``` -Internationalize a string -------------------------- +## Internationalize a string There are two types of internationalization in Pandemonium's codebase: @@ -100,8 +96,7 @@ Note: string will never match the translation as it will have the placeholder already replaced when it's passed to TranslationServer. -Clamp a value -------------- +## Clamp a value Pandemonium provides macros for clamping a value with a lower bound (`MAX`), an upper bound (`MIN`) or both (`CLAMP`): @@ -118,8 +113,7 @@ upper bound (`MIN`) or both (`CLAMP`): This works with any type that can be compared to other values (like `int` and `float`). -Microbenchmarking ------------------ +## Microbenchmarking If you want to benchmark a piece of code but don't know how to use a profiler, use this snippet: @@ -138,14 +132,12 @@ declaration. Note: - You may have to `#include "core/os/os.h"` if it's not present already. When opening a pull request, make sure to remove this snippet as well as the include if it wasn't there previously. -Get project/editor settings ---------------------------- +## Get project/editor settings There are four macros available for this: @@ -172,8 +164,7 @@ repetition: It's recommended to use `GLOBAL_DEF`/`EDITOR_DEF` only once per setting and use `GLOBAL_GET`/`EDITOR_GET` in all other places where it's referenced. -Error macros ------------- +## Error macros Pandemonium features many error macros to make error reporting more convenient. diff --git a/05_engine_development/02_cpp/03_core_types.md b/05_engine_development/02_cpp/03_core_types.md index d3021c6..cf8715f 100644 --- a/05_engine_development/02_cpp/03_core_types.md +++ b/05_engine_development/02_cpp/03_core_types.md @@ -1,7 +1,6 @@ -Core types -========== +# Core types Pandemonium has a rich set of classes and templates that compose its core, and everything is built upon them. @@ -9,8 +8,7 @@ and everything is built upon them. This reference will try to list them in order for their better understanding. -Definitions ------------ +## Definitions Pandemonium uses the standard C99 datatypes, such as `uint8_t`, `uint32_t`, `int64_t`, etc. which are nowadays supported by every @@ -31,13 +29,11 @@ many architectures have 4 bytes long wchar_t, where 2 bytes might be desired. However, by default, this has not been forced and CharType maps directly to wchar_t. -References: -~~~~~~~~~~~ +### References: - `core/typedefs.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/typedefs.h )` -Memory model ------------- +## Memory model PC is a wonderful architecture. Computers often have gigabytes of RAM, terabytes of storage and gigahertz of CPU, and when an application needs @@ -70,8 +66,7 @@ be locked to be accessed, and if an allocation runs out of memory, the pool will be rearranged and compacted on demand. Depending on the need of the game, the programmer can configure the dynamic memory pool size. -Allocating memory ------------------ +## Allocating memory Pandemonium has many tools for tracking memory usage in a game, especially during debug. Because of this, the regular C and C++ library calls @@ -128,14 +123,12 @@ locked until they go out of scope. However, PoolVectors should be used for small, dynamic memory operations, as read() and write() are too slow for a large amount of accesses. -References: -~~~~~~~~~~~ +### References: - `core/os/memory.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/os/memory.h )` - `core/pool_vector.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/pool_vector.cpp )` -Containers ----------- +## Containers Pandemonium provides also a set of common containers: @@ -162,29 +155,25 @@ The Vector<> class also has a few nice features: - It supports multi-threading, by using atomic operations on the reference counter. -References: -~~~~~~~~~~~ +### References: - `core/vector.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/vector.h )` - `core/list.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/list.h )` - `core/set.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/set.h )` - `core/map.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/map.h )` -String ------- +## String Pandemonium also provides a String class. This class has a huge amount of features, full Unicode support in all the functions (like case operations) and utf8 parsing/extracting, as well as helpers for conversion and visualization. -References: -~~~~~~~~~~~ +### References: - `core/ustring.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/ustring.h )` -StringName ----------- +## StringName StringNames are like a String, but they are unique. Creating a StringName from a string results in a unique internal pointer for all @@ -194,42 +183,35 @@ identifier, as comparing them is basically comparing a pointer. Creation of a StringName (especially a new one) is slow, but comparison is fast. -References: -~~~~~~~~~~~ +### References: - `core/string_name.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/string_name.h )` -Math types ----------- +## Math types There are several linear math types available in the core/math directory. -References: -~~~~~~~~~~~ +### References: - `core/math ( https://github.com/Relintai/pandemonium_engine/tree/3.x/core/math )` -NodePath --------- +## NodePath This is a special datatype used for storing paths in a scene tree and referencing them fast. -References: -~~~~~~~~~~~ +### References: - `core/node_path.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/node_path.h )` -RID ---- +## RID RIDs are resource IDs. Servers use these to reference data stored in them. RIDs are opaque, meaning that the data they reference can't be accessed directly. RIDs are unique, even for different types of referenced data. -References: -~~~~~~~~~~~ +### References: - `core/rid.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/rid.h )` diff --git a/05_engine_development/02_cpp/04_variant_class.md b/05_engine_development/02_cpp/04_variant_class.md index 02d5129..5ae3ed0 100644 --- a/05_engine_development/02_cpp/04_variant_class.md +++ b/05_engine_development/02_cpp/04_variant_class.md @@ -1,10 +1,8 @@ -Variant class -============= +# Variant class -About ------ +## About Variant is the most important datatype of Pandemonium, it's the most important class in the engine. A Variant takes up only 20 bytes and can store @@ -34,13 +32,11 @@ Basically, thanks to the Variant class, writing Pandemonium itself was a much, much easier task, as it allows for highly dynamic constructs not common of C++ with little effort. Become a friend of Variant today. -References: -~~~~~~~~~~~ +### References: - `core/variant.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/variant.h )` -Containers: Dictionary and Array --------------------------------- +## Containers: Dictionary and Array Both are implemented using variants. A Dictionary can match any datatype used as key to any other datatype. An Array just holds an array of @@ -53,8 +49,7 @@ desired. Copy-on-write (COW) mode support for containers was dropped with Pandemonium 3.0. -References: -~~~~~~~~~~~ +### References: - `core/dictionary.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/dictionary.h )` - `core/array.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/array.h )` diff --git a/05_engine_development/02_cpp/05_object_class.md b/05_engine_development/02_cpp/05_object_class.md index 14ac194..9ca5b19 100644 --- a/05_engine_development/02_cpp/05_object_class.md +++ b/05_engine_development/02_cpp/05_object_class.md @@ -1,16 +1,12 @@ - -Object class -============ +# Object class See also: - This page describes the C++ implementation of objects in Pandemonium. Looking for the Object class reference? `Have a look here.` -General definition ------------------- +## General definition `Object` is the base class for almost everything. Most classes in Pandemonium inherit directly or indirectly from it. Objects provide reflection and @@ -33,13 +29,11 @@ This makes Objects gain a lot of functionality, like for example obj2 = Object::cast_to(obj); // converting between classes, this also works without RTTI enabled. ``` -References: -~~~~~~~~~~~ +### References: - `core/object.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/object.h )` -Registering an Object ---------------------- +## Registering an Object ClassDB is a static class that holds the entire list of registered classes that inherit from Object, as well as dynamic bindings to all @@ -91,13 +85,11 @@ If just adding modules and functionality that is not expected to be documented as thoroughly, the `D_METHOD()` macro can safely be ignored and a string passing the name can be passed for brevity. -References: -~~~~~~~~~~~ +### References: - `core/class_db.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/class_db.h )` -Constants ---------- +## Constants Classes often have enums such as: @@ -122,8 +114,7 @@ The constants can also be bound inside `bind_methods`, by using: BIND_CONSTANT(MODE_SECOND); ``` -Properties (set/get) --------------------- +## Properties (set/get) Objects export properties, properties are useful for the following: @@ -177,8 +168,7 @@ This creates the property using the setter and the getter. -Binding properties using `set`/`get`/`get_property_list` ------------------------------------------------------------------ +## Binding properties using `set`/`get`/`get_property_list` An additional method of creating properties exists when more flexibility is desired (i.e. adding or removing properties on context). @@ -198,8 +188,7 @@ call). This is also a little less efficient since `p_property` must be compared against the desired names in serial order. -Dynamic casting ---------------- +## Dynamic casting Pandemonium provides dynamic casting between Object-derived classes, for example: @@ -216,8 +205,7 @@ works fine (although a bit slower) when RTTI is disabled. This is useful on platforms where a small binary size is ideal, such as HTML5 or consoles (with low memory footprint). -Signals -------- +## Signals Objects can have a set of signals defined (similar to Delegates in other languages). Connecting to them is rather easy: @@ -238,15 +226,13 @@ Adding signals to a class is done in `bind_methods`, using the ADD_SIGNAL(MethodInfo("been_killed")) ``` -Notifications -------------- +## Notifications All objects in Pandemonium have a `notification` method that allows it to respond to engine level callbacks that may relate to it. More information can be found on the `doc_pandemonium_notifications` page. -References ----------- +## References `Reference` inherits from Object and holds a reference count. It is the base for reference counted object types. @@ -263,13 +249,11 @@ Declaring them must be done using Ref<> template. For example: `myref` is reference counted. It will be freed when no more Ref<> templates point to it. -References: -~~~~~~~~~~~ +### References: - `core/reference.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/reference.h )` -Resources: ----------- +## Resources: `Resource` inherits from Reference, so all resources are reference counted. Resources can optionally contain a path, which @@ -279,13 +263,11 @@ resources can have the same path, attempt to do so will result in an error. Resources without a path are fine too. -References: -~~~~~~~~~~~ +### References: - `core/resource.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/resource.h )` -Resource loading ----------------- +## Resource loading Resources can be loaded with the ResourceLoader API, like this: @@ -300,13 +282,11 @@ the same time. - resourceinteractiveloader (TODO) -References: -~~~~~~~~~~~ +### References: - `core/io/resource_loader.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/io/resource_loader.h )` -Resource saving ---------------- +## Resource saving Saving a resource can be done with the resource saver API: @@ -319,7 +299,6 @@ saved as a reference to that resource. Sub resources without a path will be bundled with the saved resource and assigned sub-IDs, like `res://someresource.res::1`. This also helps to cache them when loaded. -References: -~~~~~~~~~~~ +### References: - `core/io/resource_saver.h ( https://github.com/Relintai/pandemonium_engine/blob/3.x/core/io/resource_saver.h )` diff --git a/05_engine_development/02_cpp/06_inheritance_class_tree.md b/05_engine_development/02_cpp/06_inheritance_class_tree.md index 5915d21..288f4be 100644 --- a/05_engine_development/02_cpp/06_inheritance_class_tree.md +++ b/05_engine_development/02_cpp/06_inheritance_class_tree.md @@ -1,29 +1,24 @@ -Inheritance class tree -====================== -Object ------- +# Inheritance class tree + +## Object ![](img/Object.png) -Reference ---------- +## OReference ![](img/Reference.png) -Control -------- +## OControl ![](img/Control.png) -Node2D ------- +## ONode2D ![](img/Node2D.png) -Spatial -------- +## OSpatial ![](img/Spatial.png) -Source files: :download:`tree.zip (); + ClassDB::register_class<Summator>(); } void unregister_summator_types() { @@ -225,8 +220,7 @@ Note: as subclasses. This can be raised to 13 by including the header file `core/method_bind_ext.gen.inc`. -Using the module ----------------- +## Using the module You can now use your newly created module from any script: @@ -253,11 +247,10 @@ Warning: template you plan to use, then specify the path to the custom template in each export preset. Otherwise, you'll get errors when running the project as the module isn't compiled in the export - template. See the `Compiling ..." to include in what will be committed) + (use "git add <file>..." to include in what will be committed) doc/classes/MyClass2D.xml doc/classes/MyClass4D.xml @@ -488,8 +479,8 @@ Tip: 3. Now we can generate the documentation: -We can do this via running Pandemonium's doctool i.e. `pandemonium --doctool --doctool . + user@host:~/pandemonium/bin$ ./bin/<pandemonium_binary> --doctool . ``` Now if you go to the `pandemonium/modules/summator/doc_classes` folder, you will see @@ -517,7 +508,7 @@ the things that you previously added. Of course if you point it to your pandemon folder, make sure you don't lose work by extracting older docs from an older engine build on top of the newer ones. -Note that if you don't have write access rights to your supplied `** in the dropdown that appears. + **Filter Module to <Pandemonium executable name>** in the dropdown that appears. - Your results window should now look something like this: ![](img/cpp_profiler_verysleepy_results_filtered.png) -HotSpot -^^^^^^^ +#### HotSpot - Open HotSpot. Click **Record Data**: @@ -136,8 +127,7 @@ Note: This process attachment-based workflow is similar to the one used by VerySleepy. -Xcode Instruments -^^^^^^^^^^^^^^^^^ +#### Xcode Instruments - Open Xcode. Select **Open Developer Tool** - **Instruments** from the **Xcode** app menu: - Double-click on **Time Profiler** in the **Instruments** window: diff --git a/05_engine_development/02_cpp/configuring_an_ide/01_android_studio.md b/05_engine_development/02_cpp/configuring_an_ide/01_android_studio.md index 0a23c65..6d0cff2 100644 --- a/05_engine_development/02_cpp/configuring_an_ide/01_android_studio.md +++ b/05_engine_development/02_cpp/configuring_an_ide/01_android_studio.md @@ -1,28 +1,24 @@ -Android Studio -============== +# Android Studio `Android Studio ( https://developer.android.com/studio )` is a free `JetBrains ( https://www.jetbrains.com/ )` IDE for Android development. It has a feature-rich editor which supports Java and C/C++. It can be used to work on Pandemonium's core engine as well as the Android platform codebase. -Importing the project ---------------------- +## Importing the project - From the Android Studio's welcome window select **Open an existing Android Studio project**. -.. figure:: img/android_studio_setup_project_1.png) - :figclass: figure-w480 - :align: center - - Android Studio's welcome window. +![figure-w480](img/android_studio_setup_project_1.png) + +Android Studio's welcome window. - Navigate to `/platform/android/java` and select the `settings.gradle` file. - Android Studio will import and index the project. -- To build the project, follow the `compiling instructions CMake > Change Project Root** from the top menu and select the Pandemonium root folder. -.. figure:: img/clion_3_change_project_root.png) - :align: center +![](img/clion_3_change_project_root.png) - You should be now be able to see all the project files. Autocomplete should work once the project has finished indexing. @@ -43,8 +38,7 @@ which can also be used by CLion. If you run into any issues, ask for help in one of `Pandemonium's community channels ( https://pandemoniumengine.org/community )`. -Debugging the project ---------------------- +## Debugging the project Since CLion does not support SCons, you won't be able to compile, launch, and debug Pandemonium from CLion in one step. You will first need to `compile pandemonium yourself ( https://docs.pandemoniumengine.org/en/stable/development/compiling/index.html )` and run the binary without CLion. You will then be able to debug Pandemonium by using the `Attach to process ( https://www.jetbrains.com/help/clion/attaching-to-local-process.html )` feature. @@ -55,18 +49,15 @@ You will first need to `compile pandemonium yourself ( https://docs.pandemoniume - In CLion, go to **Run > Attach to Process...** -.. figure:: img/clion_4_select_attach_to_process.png) - :align: center +![](img/clion_4_select_attach_to_process.png) - Find and Select pandemonium in the list (or type the binary name/Process ID) -.. figure:: img/clion_5_select_pandemonium_process.png) - :align: center +![](img/clion_5_select_pandemonium_process.png) You can now use the debugging tools from CLion. Note: - If you run the binary without any arguments, you will only debug the project manager window. Don't forget to add the `--path path/to/your/pandemonium/project` argument to debug a project. diff --git a/05_engine_development/02_cpp/configuring_an_ide/03_code_blocks.md b/05_engine_development/02_cpp/configuring_an_ide/03_code_blocks.md index b11010f..ac34fec 100644 --- a/05_engine_development/02_cpp/configuring_an_ide/03_code_blocks.md +++ b/05_engine_development/02_cpp/configuring_an_ide/03_code_blocks.md @@ -1,129 +1,91 @@ -Code::Blocks -============ +# Code::Blocks `Code::Blocks ( https://codeblocks.org/ )` is a free, open source, cross platform IDE. -Creating a new project ----------------------- +## Creating a new project From Code::Blocks' main screen, click **Create a new project** or select **File > New > Project...**. -.. figure:: img/code_blocks_file_new_project.png) - :figclass: figure-w480 - :align: center +![](img/code_blocks_file_new_project.png) In the **New from template** window, from **Projects**, select **Empty project**, and click **Go**. -.. figure:: img/code_blocks_new_empty_project.png) - :figclass: figure-w480 - :align: center +![](img/code_blocks_new_empty_project.png) Click Next, to pass the welcome to the new empty project wizard. -.. figure:: img/code_blocks_wizard_welcome.png) - :figclass: figure-w480 - :align: center +![](img/code_blocks_wizard_welcome.png) The project file should be created in the root of the cloned project folder. To achieve this, first, ensure that the **Project title** is the same as the folder name that Pandemonium was cloned into. Unless you cloned the project into a folder with a different name, this will be `pandemonium`. Second, ensure that the **Folder to create project in** is the folder you ran the Git clone command from, not the `pandemonium` project folder. Confirm that the **Resulting filename** field will create the project file in the root of the cloned project folder. -.. figure:: img/code_blocks_project_title_and_location.png) - :figclass: figure-w480 - :align: center +![](img/code_blocks_project_title_and_location.png) The compiler and configuration settings are managed through **SCons** and will be configured later. However, it's worth deselecting the **Create "Release" configuration** option; so only a single build target is created before clicking **Finish**. -.. figure:: img/code_blocks_compiler_and_configuration.png) - :figclass: figure-w480 - :align: center +![](img/code_blocks_compiler_and_configuration.png) -Configuring the build ---------------------- +## Configuring the build The first step is to change the project properties. Right-click on the new project and select **Properties...**. -.. figure:: img/code_blocks_open_properties.png) - :figclass: figure-w480 - :align: center +![](img/code_blocks_open_properties.png) Check the **This is a custom Makefile** property. Click OK to save the changes. -.. figure:: img/code_blocks_project_properties.png) - :figclass: figure-w480 - :align: center +![](img/code_blocks_project_properties.png) The next step is to change the build options. Right-click on the new project and select **Build Options...**. -.. figure:: img/code_blocks_open_build_options.png) - :figclass: figure-w480 - :align: center +![](img/code_blocks_open_build_options.png) Select the **"Make" commands** tab and remove all the existing commands for all the build targets. For each build target enter the **SCons** command for creating the desired build in the **Build project/target** field. The minimum is `scons`. For details on the **SCons** build options, see `doc_introduction_to_the_buildsystem`. It's also useful to add the `scons --clean` command in the **Clean project/target** field to the project's default commmands. If you're using Windows, all the commands need to be preceded with `cmd /c` to iniitalize the command interpreter. -.. figure:: img/code_blocks_scons_minimum.png) - :figclass: figure-w480 - :align: center +![](img/code_blocks_scons_minimum.png) -.. figure:: img/code_blocks_scons_clean.png) - :figclass: figure-w480 - :align: center +![](img/code_blocks_scons_clean.png) Windows example: -.. figure:: img/code_blocks_scons_windows.png) - :figclass: figure-w480 - :align: center +!{}(img/code_blocks_scons_windows.png) Code::Blocks should now be configured to build Pandemonium; so either select **Build > Build**, click the gear button, or press :kbd:`Ctrl + F9`. -Configuring the run -------------------- +## Configuring the run Once **SCons** has successfully built the desired target, reopen the project **Properties...** and select the **Build targets** tab. In the **Output filename** field, browse to the `bin` folder and select the compiled file. Deselect the **Auto-generate filename prefix** and **Auto-generate filename extension** options. -.. figure:: img/code_blocks_build_targets.png) - :figclass: figure-w480 - :align: center +![](img/code_blocks_build_targets.png) Code::Blocks should now be configured to run your compiled Pandemonium executable; so either select **Build > Run**, click the green arrow button, or press :kbd:`Ctrl + F10`. There are two additional points worth noting. First, if required, the **Execution working dir** field can be used to test specific projects, by setting it to the folder containing the `project.pandemonium` file. Second, the **Build targets** tab can be used to add and remove build targets for working with and creating different builds. -Adding files to the project ---------------------------- +## Adding files to the project To add all the Pandemonium code files to the project, right-click on the new project and select **Add files recursively...**. -.. figure:: img/code_blocks_add_files_recursively.png) - :figclass: figure-w480 - :align: center +![](img/code_blocks_add_files_recursively.png) It should automatically select the project folder; so simply click **Open**. By default, all code files are included, so simply click **OK**. -.. figure:: img/code_blocks_select_files.png) - :figclass: figure-w480 - :align: center +![](img/code_blocks_select_files.png) -Code style configuration ------------------------- +## Code style configuration Before editing any files, remember that all code needs to comply with the `doc_code_style_guidelines`. One important difference with Pandemonium is the use of tabs for indents. Therefore, the key default editor setting that needs to be changed in Code::Blocks is to enable tabs for indents. This setting can be found by selecting **Settings > Editor**. -.. figure:: img/code_blocks_update_editor_settings.png) - :figclass: figure-w480 - :align: center +![](img/code_blocks_update_editor_settings.png) Under **General Settings**, on the **Editor Settings** tab, under **Tab Options** check **Use TAB character**. -.. figure:: img/code_block_use_tab_character.png) - :figclass: figure-w480 - :align: center +![](img/code_block_use_tab_character.png) That's it. You're ready to start contributing to Pandemonium using the Code::Blocks IDE. Remember to save the project file and the **Workspace**. If you run into any issues, ask for help in one of `Pandemonium's community channels ( https://pandemoniumengine.org/community )`. diff --git a/05_engine_development/02_cpp/configuring_an_ide/04_kdevelop.md b/05_engine_development/02_cpp/configuring_an_ide/04_kdevelop.md index 8f6f7e7..2fc6c2d 100644 --- a/05_engine_development/02_cpp/configuring_an_ide/04_kdevelop.md +++ b/05_engine_development/02_cpp/configuring_an_ide/04_kdevelop.md @@ -1,34 +1,26 @@ -KDevelop -======== +# KDevelop `KDevelop ( https://www.kdevelop.org )` is a free, open source IDE for all desktop platforms. -Importing the project ---------------------- +## Importing the project - From the KDevelop's main screen select **Open Project**. -.. figure:: img/kdevelop_newproject.png) - :figclass: figure-w480 - :align: center +![](img/kdevelop_newproject.png) - KDevelop's main screen. +KDevelop's main screen. - Navigate to the Pandemonium root folder and select it. - On the next screen, choose **Custom Build System** for the **Project Manager**. -.. figure:: img/kdevelop_custombuild.png) - :figclass: figure-w480 - :align: center +![](img/kdevelop_custombuild.png) - After the project has been imported, open the project configuration by right-clicking on it in the **Projects** panel and selecting **Open Configuration..** option. -.. figure:: img/kdevelop_openconfig.png) - :figclass: figure-w480 - :align: center +![](img/kdevelop_openconfig.png) - Under **Language Support** open the **Includes/Imports** tab and add the following paths: @@ -42,46 +34,35 @@ Importing the project corresponding to your current platform ``` -.. figure:: img/kdevelop_addincludes.png) - :figclass: figure-w480 - :align: center +![](img/kdevelop_addincludes.png) - Apply the changes. - Under **Custom Build System** add a new build configuration with the following settings: - +-----------------+------------------------------------------------------------------------------+ - | Build Directory | *blank* | - +-----------------+------------------------------------------------------------------------------+ - | Enable | **True** | - +-----------------+------------------------------------------------------------------------------+ - | Executable | **scons** | - +-----------------+------------------------------------------------------------------------------+ - | Arguments | See `doc_introduction_to_the_buildsystem` for a full list of arguments. | - +-----------------+------------------------------------------------------------------------------+ +| | | +|-----------------|------------------------------------------------------------------------------| +| Build Directory | *blank* | +| Enable | **True** | +| Executable | **scons** | +| Arguments | See `doc_introduction_to_the_buildsystem` for a full list of arguments. | -.. figure:: img/kdevelop_buildconfig.png) - :figclass: figure-w480 - :align: center + +![](img/kdevelop_buildconfig.png) - Apply the changes and close the configuration window. -Debugging the project ---------------------- +## Debugging the project - Select **Run > Configure Launches...** from the top menu. -.. figure:: img/kdevelop_configlaunches.png) - :figclass: figure-w480 - :align: center +![](img/kdevelop_configlaunches.png) - Click **Add** to create a new launch configuration. - Select **Executable** option and specify the path to your executable located in the `/bin` folder. The name depends on your build configuration, e.g. `pandemonium.x11.tools.64` for 64-bit X11 platform with `tools` enabled. -.. figure:: img/kdevelop_configlaunches2.png) - :figclass: figure-w480 - :align: center +![](img/kdevelop_configlaunches2.png) If you run into any issues, ask for help in one of `Pandemonium's community channels ( https://pandemoniumengine.org/community )`. diff --git a/05_engine_development/02_cpp/configuring_an_ide/05_qt_creator.md b/05_engine_development/02_cpp/configuring_an_ide/05_qt_creator.md index 9cf9560..cf5c223 100644 --- a/05_engine_development/02_cpp/configuring_an_ide/05_qt_creator.md +++ b/05_engine_development/02_cpp/configuring_an_ide/05_qt_creator.md @@ -1,78 +1,60 @@ -Qt Creator -========== +# Qt Creator `Qt Creator ( https://doc.qt.io/qtcreator/index.html )` is a free, open source IDE for all desktop platforms. -Importing the project ---------------------- +## Importing the project - From the Qt Creator's main screen select **New Project > Import Project > Import Existing Project**. -.. figure:: img/qtcreator-new-project.png) - :figclass: figure-w480 - :align: center +![](img/qtcreator-new-project.png) - Under **Location** select the Pandemonium root folder. -.. figure:: img/qtcreator-set-project-path.png) - :figclass: figure-w480 - :align: center +![](img/qtcreator-set-project-path.png) - Next, you can choose which folders and files will be visible to the project. While C/C++ files are added automatically, other extensions can be potentially useful: `*.glsl` for shader files, `*.py` for buildsystem files, `*.java` for Android platform development, `*.mm` for macOS platform development. -.. figure:: img/qtcreator-apply-import-filter.png) - :figclass: figure-w480 - :align: center +![](img/qtcreator-apply-import-filter.png) Note: You can change this configuration later by right-clicking on your project and selecting the **Edit Files...** option. - .. figure:: img/qtcreator-edit-files-menu.png) - :figclass: figure-w480 - :align: center +![](img/qtcreator-edit-files-menu.png) - Finish the import. - Open the `project_name.includes` file and add a line containing `.` to it to correctly enable the code completion. -.. figure:: img/qtcreator-project-name-includes.png) - :figclass: figure-w480 - :align: center +![](img/qtcreator-project-name-includes.png) - From the left-side menu select **Projects** and open the **Build** tab. - Delete the predefined `make` build step. -.. figure:: img/qtcreator-projects-build.png) - :figclass: figure-w480 - :align: center +![](img/qtcreator-projects-build.png) - Click **Add Build Step > Custom Process Step** to add a new build step with the following settings: - +-----------+------------------------------------------------------------------------------+ - | Command | **scons** | - +-----------+------------------------------------------------------------------------------+ - | Arguments | See `doc_introduction_to_the_buildsystem` for a full list of arguments. | - +-----------+------------------------------------------------------------------------------+ +| | | +|-----------|------------------------------------------------------------------------------| +| Command | **scons** | +| Arguments | See `doc_introduction_to_the_buildsystem` for a full list of arguments. | -.. figure:: img/qtcreator-set-scons-command.png) - :figclass: figure-w480 - :align: center +![](img/qtcreator-set-scons-command.png) Note: If the build fails with `Could not start process "scons"`, it can mean that `scons` is not in your `PATH` environment variable. In this case, you'll have to specify the full path to the SCons binary. -Debugging the project ---------------------- +## Debugging the project - From the left-side menu select **Projects** and open the **Run** tab. - Under **Executable** specify the path to your executable located in @@ -82,32 +64,25 @@ Debugging the project - If you want to run a specific project, specify its root folder under **Working directory**. - If you want to run the editor, add `-e` to the **Command line arguments** field. -.. figure:: img/qtcreator-run-command.png) - :figclass: figure-w480 - :align: center +![](img/qtcreator-run-command.png) To learn more about command line arguments, refer to the `command line tutorial ( doc_command_line_tutorial )`. -Code style configuration ------------------------- +## Code style configuration Developers must follow the project's `code style ( doc_code_style_guidelines )` and the IDE should help them follow it. By default, Qt Creator uses spaces for indentation which doesn't match the Pandemonium code style guidelines. You can change this behavior by changing the **Code Style** in **Tools > Options > C++**. -.. figure:: img/qtcreator-options-cpp.png) - :figclass: figure-w480 - :align: center +![](img/qtcreator-options-cpp.png) Click on **Edit** to change the current settings, then click on **Copy Built-in Code Style** button to set a new code style. Set a name for it (e.g. Pandemonium) and change the Tab policy to be **Tabs Only**. -.. figure:: img/qtcreator-edit-codestyle.png) - :figclass: figure-w480 - :align: center +![](img/qtcreator-edit-codestyle.png) If you run into any issues, ask for help in one of `Pandemonium's community channels ( https://pandemoniumengine.org/community )`. diff --git a/05_engine_development/02_cpp/configuring_an_ide/06_visual_studio.md b/05_engine_development/02_cpp/configuring_an_ide/06_visual_studio.md index c52e043..65210f0 100644 --- a/05_engine_development/02_cpp/configuring_an_ide/06_visual_studio.md +++ b/05_engine_development/02_cpp/configuring_an_ide/06_visual_studio.md @@ -1,15 +1,13 @@ -Visual Studio -============= +# Visual Studio `Visual Studio Community ( https://visualstudio.microsoft.com )` is a Windows-only IDE by `Microsoft ( https://microsoft.com )` that's free for non-commercial use. It has many useful features, such as memory view, performance view, source control and more. -Importing the project ---------------------- +## Importing the project Visual Studio requires a solution file to work on a project. While Pandemonium does not come with the solution file, it can be generated using SCons. @@ -21,14 +19,13 @@ with the solution file, it can be generated using SCons. - Use the **Build** top menu to build the project. Warning: + Visual Studio must be configured with the C++ package. It can be selected in the intaller: - .. figure:: img/vs_1_install_cpp_package.png) - :align: center +![](img/vs_1_install_cpp_package.png) -Debugging the project ---------------------- +## Debugging the project Visual Studio features a powerful debugger. This allows the user to examine Pandemonium's source code, stop at specific points in the code, inspect the current execution context, @@ -42,16 +39,14 @@ project manager opens a project, the initial process is terminated and the debug - To configure the launch options to use with the debugger use **Project > Properties** from the top menu: -.. figure:: img/vs_2_project_properties.png) - :align: center +![](img/vs_2_project_properties.png) - Open the **Debugging** section and under **Command Arguments** add two new arguments: the `-e` flag opens the editor instead of the project manager, and the `--path` argument tells the executable to open the specified project (must be provided as an *absolute* path to the project root, not the `project.pandemonium` file). -.. figure:: img/vs_3_debug_command_line.png) - :align: center +![](img/vs_3_debug_command_line.png) To learn more about command line arguments, refer to the `command line tutorial ( doc_command_line_tutorial )`. @@ -62,8 +57,7 @@ process using **Debug > Attach to Process...** menu. To check that everything is working, put a breakpoint in `main.cpp` and press :kbd:`F5` to start debugging. -.. figure:: img/vs_4_debugging_main.png) - :align: center +![](img/vs_4_debugging_main.png) If you run into any issues, ask for help in one of `Pandemonium's community channels ( https://pandemoniumengine.org/community )`. diff --git a/05_engine_development/02_cpp/configuring_an_ide/07_visual_studio_code.md b/05_engine_development/02_cpp/configuring_an_ide/07_visual_studio_code.md index 19e585d..e41d34e 100644 --- a/05_engine_development/02_cpp/configuring_an_ide/07_visual_studio_code.md +++ b/05_engine_development/02_cpp/configuring_an_ide/07_visual_studio_code.md @@ -1,13 +1,11 @@ -Visual Studio Code -================== +# Visual Studio Code `Visual Studio Code ( https://code.visualstudio.com )` is a free cross-platform code editor by `Microsoft ( https://microsoft.com )` (not to be confused with `doc_configuring_an_ide_vs`). -Importing the project ---------------------- +## Importing the project - Make sure the C/C++ extension is installed. You can find instructions in the `official documentation ( https://code.visualstudio.com/docs/languages/cpp )`. @@ -18,18 +16,15 @@ Importing the project **File > Open Folder...**. - Press :kbd:`Ctrl + Shift + P` to open the command prompt window and enter *Configure Task*. -.. figure:: img/vscode_configure_task.png) - :align: center +![](img/vscode_configure_task.png) - Select the **Create tasks.json file from template** option. -.. figure:: img/vscode_create_tasksjson.png) - :align: center +![](img/vscode_create_tasksjson.png) - Then select **Others**. -.. figure:: img/vscode_create_tasksjson_others.png) - :align: center +![](img/vscode_create_tasksjson_others.png) - Within the `tasks.json` file find the `"tasks"` array and add a new section to it: @@ -66,25 +61,21 @@ js Windows } ``` -.. figure:: img/vscode_3_tasks.json.png) - :figclass: figure-w480 - :align: center +![](img/vscode_3_tasks.json.png) - An example of a filled out `tasks.json`. +An example of a filled out `tasks.json`. Arguments can be different based on your own setup and needs. See `doc_introduction_to_the_buildsystem` for a full list of arguments. -Debugging the project ---------------------- +## Debugging the project To run and debug the project you need to create a new configuration in the `launch.json` file. - Press :kbd:`Ctrl + Shift + D` to open the Run panel. - If `launch.json` file is missing you will be prompted to create a new one. -.. figure:: img/vscode_1_create_launch.json.png) - :align: center +![](img/vscode_1_create_launch.json.png) - Select **C++ (GDB/LLDB)**. There may be another platform specific option here. If selected, adjust the configuration example provided accordingly. @@ -159,9 +150,7 @@ js Windows } ``` -.. figure:: img/vscode_2_launch.json.png) - :figclass: figure-w480 - :align: center +![](img/vscode_2_launch.json.png) An example of a filled out `launch.json`. diff --git a/05_engine_development/02_cpp/configuring_an_ide/08_xcode.md b/05_engine_development/02_cpp/configuring_an_ide/08_xcode.md index fabc75b..eeda67b 100644 --- a/05_engine_development/02_cpp/configuring_an_ide/08_xcode.md +++ b/05_engine_development/02_cpp/configuring_an_ide/08_xcode.md @@ -1,47 +1,35 @@ - -Xcode -===== +# Xcode `Xcode ( https://developer.apple.com/xcode )` is a free macOS-only IDE. You can download it from the Mac App Store. -Importing the project ---------------------- +## Importing the project - From Xcode's main screen create a new project using the **Other > External Build System** template. -.. figure:: img/xcode_1_create_external_build_project.png) - :figclass: figure-w480 - :align: center +![](img/xcode_1_create_external_build_project.png) - Open your build targets from the **Targets** section and select the **Info** tab. - Fill out the form with the following settings: - +------------+------------------------------------------------------------------------------+ - | Build Tool | A full path to the **scons** executable, e.g. **/usr/local/bin/scons** | - +------------+------------------------------------------------------------------------------+ - | Arguments | See `doc_introduction_to_the_buildsystem` for a full list of arguments. | - +------------+------------------------------------------------------------------------------+ - | Directory | A full path to the Pandemonium root folder | - +------------+------------------------------------------------------------------------------+ +| | | +|------------|------------------------------------------------------------------------------| +| Build Tool | A full path to the **scons** executable, e.g. **/usr/local/bin/scons** | +| Arguments | See `doc_introduction_to_the_buildsystem` for a full list of arguments. | +| Directory | A full path to the Pandemonium root folder | -.. figure:: img/xcode_2_configure_scons.png) - :figclass: figure-w480 - :align: center + +![](img/xcode_2_configure_scons.png) - Add a Command Line Tool target which will be used for indexing the project by choosing **File > New > Target...**. -.. figure:: img/xcode_3_add_new_target.png) - :figclass: figure-w480 - :align: center +![](img/xcode_3_add_new_target.png) - Select **OS X > Application > Command Line Tool**. -.. figure:: img/xcode_4_select_command_line_target.png) - :figclass: figure-w480 - :align: center +![](img/xcode_4_select_command_line_target.png) Note: Name it something so you know not to compile with this target (e.g. `PandemoniumXcodeIndex`). @@ -54,23 +42,18 @@ Note: - Add the Pandemonium source to the project by dragging and dropping it into the project file browser. - Uncheck **Create external build system project**. -.. figure:: img/xcode_5_after_add_pandemonium_source_to_project.png) - :figclass: figure-w480 - :align: center +![](img/xcode_5_after_add_pandemonium_source_to_project.png) - Next select **Create groups** for the **Added folders** option and check *only* your command line indexing target in the **Add to targets** section. -.. figure:: img/xcode_6_after_add_pandemonium_source_to_project_2.png) - :figclass: figure-w480 - :align: center +![](img/xcode_6_after_add_pandemonium_source_to_project_2.png) - Xcode will now index the files. This may take a few minutes. - Once Xcode is done indexing, you should have jump-to-definition, autocompletion, and full syntax highlighting. -Debugging the project ---------------------- +## Debugging the project To enable debugging support you need to edit the external build target's build and run schemes. @@ -85,17 +68,13 @@ To enable debugging support you need to edit the external build target's build a ln -f ${PROJECT_DIR}/pandemonium/bin/pandemonium.osx.tools.64 ${PROJECT_DIR}/pandemonium/bin/pandemonium ``` -.. figure:: img/xcode_7_setup_build_post_action.png) - :figclass: figure-w480 - :align: center +![](img/xcode_7_setup_build_post_action.png) - Build the external build target. - Open the scheme editor again and select **Run**. -.. figure:: img/xcode_8_setup_run_scheme.png) - :figclass: figure-w480 - :align: center +![](img/xcode_8_setup_run_scheme.png) - Set the **Executable** to the file you linked in your post-build action script. - Check **Debug executable**. diff --git a/05_engine_development/02_cpp/configuring_an_ide/img/clion_5_select_godot_process.png b/05_engine_development/02_cpp/configuring_an_ide/img/clion_5_select_pandemonium_process.png similarity index 100% rename from 05_engine_development/02_cpp/configuring_an_ide/img/clion_5_select_godot_process.png rename to 05_engine_development/02_cpp/configuring_an_ide/img/clion_5_select_pandemonium_process.png diff --git a/05_engine_development/02_cpp/configuring_an_ide/img/xcode_5_after_add_godot_source_to_project.png b/05_engine_development/02_cpp/configuring_an_ide/img/xcode_5_after_add_pandemonium_source_to_project.png similarity index 100% rename from 05_engine_development/02_cpp/configuring_an_ide/img/xcode_5_after_add_godot_source_to_project.png rename to 05_engine_development/02_cpp/configuring_an_ide/img/xcode_5_after_add_pandemonium_source_to_project.png diff --git a/05_engine_development/02_cpp/configuring_an_ide/img/xcode_6_after_add_godot_source_to_project_2.png b/05_engine_development/02_cpp/configuring_an_ide/img/xcode_6_after_add_pandemonium_source_to_project_2.png similarity index 100% rename from 05_engine_development/02_cpp/configuring_an_ide/img/xcode_6_after_add_godot_source_to_project_2.png rename to 05_engine_development/02_cpp/configuring_an_ide/img/xcode_6_after_add_pandemonium_source_to_project_2.png diff --git a/05_engine_development/03_editor/01_introduction_to_editor_development.md b/05_engine_development/03_editor/01_introduction_to_editor_development.md index 65dadb0..545e7db 100644 --- a/05_engine_development/03_editor/01_introduction_to_editor_development.md +++ b/05_engine_development/03_editor/01_introduction_to_editor_development.md @@ -1,7 +1,5 @@ - -Introduction to editor development -================================== +# Introduction to editor development On this page, you will learn: @@ -13,25 +11,22 @@ To create editor plugins in GDScript, see `doc_making_plugins` instead. See also: - If you are new to Pandemonium, we recommended you to read `doc_pandemonium_design_philosophy` before continuing. Since the Pandemonium editor is a Pandemonium project written in C++, much of the engine's philosophy applies to the editor. -Technical choices ------------------ +## Technical choices The Pandemonium editor is drawn using Pandemonium's renderer and -`UI system key=value key=value key=value ...]` @@ -66,8 +63,7 @@ so on. For example, a spatial node looks like: transform=Transform( 1.0, 0.0, 0.0 ,0.0, 1.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0 ) ``` -The scene tree --------------- +## The scene tree The scene tree is made up of… nodes! The heading of each node consists of its name, parent and (most of the time) a type. For example @@ -133,8 +129,7 @@ save a file with that node in it. Some example nodes are: far = 100.0 ``` -NodePath -~~~~~~~~ +### NodePath A tree structure is not enough to represent the whole scene. Pandemonium uses a `NodePath(Path/To/Node)` structure to refer to another node or attribute of @@ -158,8 +153,7 @@ the node anywhere in the scene tree. For instance, MeshInstance uses ... ``` -Skeleton -~~~~~~~~ +### Skeleton The Skeleton node inherits the Spatial node, but also may have a list of bones described in key-value pairs in the format `bones/Id/Attribute=Value`. The @@ -199,8 +193,7 @@ Here's an example of a skeleton node with two bones: bones/1/bound_children = [ ] ``` -BoneAttachment -~~~~~~~~~~~~~~ +### BoneAttachment BoneAttachment node is an intermediate node to describe some node being parented to a single bone in a Skeleton node. The BoneAttachment has a @@ -230,8 +223,7 @@ An example of one MeshInstance parented to a bone in Skeleton: transform = Transform(1.0, 0.0, 0.0, 0.0, 1.86265e-09, 1.0, 0.0, -1.0, 0.0, 0.0219986, -0.0343127, 2.25595) ``` -AnimationPlayer -~~~~~~~~~~~~~~~ +### AnimationPlayer AnimationPlayer works as an animation library. It stores animations listed in the format `anim/Name=SubResource(ResourceId)`; each line refers to an @@ -251,8 +243,7 @@ AnimationPlayer. The root node is stored as blend_times = [ ] ``` -Resources ---------- +## Resources Resources are components that make up the nodes. For example, a MeshInstance node will have an accompanying ArrayMesh resource. The ArrayMesh resource @@ -267,8 +258,7 @@ the same ID for both an internal and external resource. For example, to refer to the resource `[ext_resource id=3 type="PackedScene" path=....]`, you would use `ExtResource(3)`. -External resources -~~~~~~~~~~~~~~~~~~ +### External resources External resources are links to resources not contained within the TSCN file itself. An external resource consists of a path, a type and an ID. @@ -288,8 +278,7 @@ Like TSCN files, a TRES file may contain single-line comments starting with a semicolon (`;`). However, comments will be discarded when saving the resource using the Pandemonium editor. -Internal resources -~~~~~~~~~~~~~~~~~~ +### Internal resources A TSCN file can contain meshes, materials and other data. These are contained in the *internal resources* section of the file. The heading for an internal @@ -313,8 +302,7 @@ Unfortunately, documentation on the formats for these subresources isn't complete. Some examples can be found by inspecting saved resource files, but others can only be found by looking through Pandemonium's source. -ArrayMesh -~~~~~~~~~ +### ArrayMesh ArrayMesh consists of several surfaces, each in the format `surface\Index={}`. Each surface is a set of vertices and a material. @@ -367,8 +355,7 @@ An example of ArrayMesh: } ``` -Animation -~~~~~~~~~ +### Animation An animation resource consists of tracks. Besides, it has `length`, `loop` and `step` applied to all the tracks. diff --git a/06_community/01_tutorials.md b/06_community/01_tutorials.md index 8a22a28..e641ba5 100644 --- a/06_community/01_tutorials.md +++ b/06_community/01_tutorials.md @@ -1,14 +1,12 @@ -Tutorials and resources -======================= +# Tutorials and resources This is a list of third-party tutorials and resources created by the Pandemonium community. For resources, remember that there is the official `Pandemonium Asset Library ( https://pandemoniumengine.org/asset-library/asset )` full of official and community resources too! Also, have a look at this `huge list over at Reddit ( https://www.reddit.com/r/pandemonium/comments/an0iq5/pandemonium_tutorials_list_of_video_and_written/ )`. Think there is something missing here? Feel free to submit a `Pull Request ( https://github.com/Relintai/pandemonium_engine-docs/blob/master/community/tutorials.rst )` as always. -Where to start --------------- +## Where to start The Pandemonium video tutorials by `GDQuest ( https://www.youtube.com/channel/UCxboW7x0jZqFdvMdCFKTMsQ/playlists )`, `Game from Scratch ( https://www.youtube.com/watch?v=iDEcP8Mc-7s&list=PLS9MbmO_ssyDk79j9ewONxV88fD5e_o5d )` and `KidsCanCode ( https://www.youtube.com/channel/UCNaPQ5uLX5iIEHUCLmfAgKg/playlists )` are well-regarded in the community and often recommended as a gentle introduction to beginners. @@ -20,8 +18,7 @@ GDQuest's *Learn GDScript From Zero* is a free and open source interactive tutor Some tutorials mentioned below provide more advanced tutorials, e.g. on 3D or shaders. -Video tutorials ---------------- +## Video tutorials - `Pandemonium Tutorials ( https://www.youtube.com/channel/UCnr9ojBEQGgwbcKsZC-2rIg )` (2D, GDScript, Programming Basics). - `Emilio ( https://www.youtube.com/channel/UC9DR22-qohBDtZ74R3FxOZg )` (2D, GDScript and VisualScript). @@ -46,22 +43,19 @@ Video tutorials - `Garbaj ( https://www.youtube.com/c/Garbaj/ )` (3D, GDScript). - `Kasper Frandsen ( https://www.youtube.com/c/KasperFrandsen/ )` (3D, Shaders). -Text tutorials --------------- +## Text tutorials - `FinepointCGI website by Mitch ( http://finepointcgi.io/ )` - `GDScript website by Andrew Wilkes ( https://gdscript.com )` - `Pandemonium Recipes by KidsCanCode ( http://pandemoniumrecipes.com/ )` - `Steincodes ( https://steincodes.tumblr.com )` -Devlogs -------- +## Devlogs - `Andrea Catania (Physics & AI) ( https://www.youtube.com/channel/UCm4RuvYtgpgFDTCgaEUT5uQ/videos )` - `Bastiaan Olij (AR & VR) ( https://www.youtube.com/channel/UCrbLJYzJjDf2p-vJC011lYw/videos )` -Resources ---------- +## Resources - `awesome-pandemonium: A curated list of free/libre plugins, scripts and add-ons ( https://github.com/pandemoniumengine/awesome-pandemonium )` - `Zeef Pandemonium Engine: A curated directory of resources by Andre Schmitz ( https://pandemonium-engine.zeef.com/andre.antonio.schmitz )` diff --git a/06_community/contributing/01_introduction.md b/06_community/contributing/01_introduction.md index 10170ac..fb5f7dd 100644 --- a/06_community/contributing/01_introduction.md +++ b/06_community/contributing/01_introduction.md @@ -1,5 +1,5 @@ -Contributing -============ + +# Contributing Everyone is most welcome to contribute to Pandemonium. Here are some ways in which you can contribute to the project: @@ -11,73 +11,30 @@ can contribute to the project: - Reporting issues or `writing detailed proposals ( https://github.com/Relintai/pandemonium_engine-proposals/ )`. -Getting started ---------------- +## Getting started You would like to contribute but you don't know how or what to do? You can get answers below. -.. toctree:: - :maxdepth: 1 - :name: toc-community-getting-started - - ways_to_contribute - - - -Contributing to the engine --------------------------- +## Contributing to the engine The guides below explain how to contribute to the engine's core. You will learn about the code style, the contribution workflow, and more. -.. toctree:: - :maxdepth: 1 - :name: toc-community-contributing-to-the-engine - - best_practices_for_engine_contributors - pr_workflow - testing_pull_requests - bisecting_regressions - bug_triage_guidelines - code_style_guidelines - cpp_usage_guidelines - - - -Writing documentation ---------------------- +## Writing documentation We always need help to improve the documentation, be it the class reference or the manual. Below, you can find our content and writing guidelines and concrete guides to make changes to the documentation. -Guidelines -~~~~~~~~~~ +### Guidelines Here are the principles and guidelines we strive to follow to write accessible documentation. -.. toctree:: - :maxdepth: 1 - :name: toc-community-writing-guidelines +### Writing the manual - content_guidelines - docs_writing_guidelines - documentation_guidelines - -Writing the manual -~~~~~~~~~~~~~~~~~~ - -.. toctree:: - :maxdepth: 1 - :name: toc-community-documentation - - contributing_to_the_documentation - building_the_manual - -Class reference guides -~~~~~~~~~~~~~~~~~~~~~~ +### Class reference guides The pages below focus on the class reference. @@ -86,24 +43,8 @@ the `pandemonium repository ( https://github.com/Relintai/pandemonium_engine )`. to write it, so the process to contribute to the class reference differs from writing the online manual. -.. toctree:: - :maxdepth: 1 - :name: toc-community-class-reference - - updating_the_class_reference - class_reference_writing_guidelines - - - -Translating the documentation -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +### Translating the documentation The community is always working hard on making Pandemonium and its documentation available to more people. Localizing the documentation is a colossal and ongoing effort you can be part of. - -.. toctree:: - :maxdepth: 1 - :name: toc-community-localization - - editor_and_docs_localization diff --git a/06_community/contributing/02_ways_to_contribute.md b/06_community/contributing/02_ways_to_contribute.md index 4cd3ce8..5287913 100644 --- a/06_community/contributing/02_ways_to_contribute.md +++ b/06_community/contributing/02_ways_to_contribute.md @@ -1,7 +1,6 @@ -Ways to contribute -================== +# Ways to contribute Pandemonium Engine is a non-profit, community-driven free and open source project. Almost all (but our lead dev Juan, more on that below) developers are working @@ -50,8 +49,7 @@ positive to the engine, regardless of their skill set: some money to the project, check `our website ( https://pandemoniumengine.org/donate )` for details. -Contributing code ------------------ +## Contributing code The possibility to study, use, modify and redistribute modifications of the engine's source code are the fundamental rights that @@ -113,16 +111,14 @@ Note: Proposals are only required when working on an enhancement or a new feature. Bug reports are sufficient for fixing issues. -Testing and reporting issues ----------------------------- +## Testing and reporting issues Another great way of contributing to the engine is to test development releases or the development branch and to report issues. It is also helpful to report issues discovered in stable releases, so that they can be fixed in the development branch and in future maintenance releases. -Testing development versions -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +### Testing development versions To help with the testing, you have several possibilities: @@ -142,8 +138,7 @@ potential bugs that might still be present in the stable releases, especially when using some niche features of the engine which might get less testing by the developers. -Filing an issue on GitHub -~~~~~~~~~~~~~~~~~~~~~~~~~ +### Filing an issue on GitHub Pandemonium uses `GitHub's issue tracker ( https://github.com/Relintai/pandemonium_engine/issues )` for bug reports and enhancement suggestions. You will need a GitHub account to @@ -191,8 +186,7 @@ When you click the **New issue** button, you should be presented with a text are prefilled with our issue template. Please try to follow it so that all issues are consistent and provide the required information. -Contributing to the documentation ---------------------------------- +## Contributing to the documentation There are two separate resources referred to as "documentation" in Pandemonium: @@ -211,8 +205,7 @@ There are two separate resources referred to as "documentation" in Pandemonium: `pandemonium-docs ( https://github.com/Relintai/pandemonium_engine-docs )` GitHub repository. See `doc_contributing_to_the_documentation` for more details. -Contributing translations -------------------------- +## Contributing translations To make Pandemonium accessible to everyone, including users who may prefer resources in their native language instead of English, our community helps translate both diff --git a/06_community/contributing/03_best_practices_for_engine_contributors.md b/06_community/contributing/03_best_practices_for_engine_contributors.md index c42c806..84ec2a5 100644 --- a/06_community/contributing/03_best_practices_for_engine_contributors.md +++ b/06_community/contributing/03_best_practices_for_engine_contributors.md @@ -1,10 +1,8 @@ -Best practices for engine contributors -====================================== +# Best practices for engine contributors -Introduction ------------- +## Introduction Pandemonium has a large amount of users who have the ability to contribute, given the project itself is aimed mainly at users with the ability to do programming. @@ -12,8 +10,7 @@ Despite this, not all of them have the same level of experience working in large projects or in software engineering, which can lead to common misunderstandings and bad practices during the process of contributing code to the project. -Language --------- +## Language The scope of this document is to be a list of best practices for contributors to follow, as well as to create a language they can use to refer to common @@ -27,11 +24,9 @@ Contributions are most of the time categorized as bug fixes, enhancements or new features. To abstract this idea, we will call them *Solutions*, because they always seek to solve something that can be described as a *Problem*. -Best Practices --------------- +## Best Practices -#1: The problem always comes first -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +### 1: The problem always comes first Many contributors are extremely creative and just enjoy the process of designing abstract data structures, creating nice user interfaces, or simply love @@ -46,8 +41,7 @@ as source and binary and requires maintenance once it exists. Avoiding the addition of anything unnecessary is always considered a good practice in software development. -#2: To solve the problem, it has to exist in the first place -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +### 2: To solve the problem, it has to exist in the first place This is a variation of the previous practice. Adding anything unnecessary is not a good idea, but what constitutes what is necessary and what isn't? @@ -72,8 +66,7 @@ This is generally considered a bad habit because trying to solve problems that written but never used, or that is considerably more complex to use and maintain than it needs to be. -#3: The problem has to be complex or frequent -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +### 3: The problem has to be complex or frequent Software is designed to solve problems, but we can't expect it to solve *every problem that exists under the sun*. As a game engine, Pandemonium will solve problems @@ -101,8 +94,7 @@ In our experience, in most cases it's usually obvious to tell when a problem is complex or frequent, but cases may arise where drawing this line is difficult. This is why discussing with other developers (next point) is always advised. -#4: The solution must be discussed with others -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +### 4: The solution must be discussed with others It is often the case that when users stumble upon problems, they are only immersed in their project, so they will naturally try to solve the problem @@ -133,8 +125,7 @@ performance. Performance optimizations will be considered, but they may not be accepted if they make something too difficult to use or if they add too much complexity to the codebase. -#5: To each problem, its own solution -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +### 5: To each problem, its own solution For programmers, it is always a most enjoyable challenge to find the most optimal solutions to problems. Things, however, may go overboard sometimes and @@ -160,8 +151,7 @@ Big and flexible solutions also have an additional drawback which is that, over time, they are rarely flexible enough for all users, who keep requesting more functions added (and making the API and codebase more and more complex). -#6: Cater to common use cases, leave the door open for the rare ones -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +### 6: Cater to common use cases, leave the door open for the rare ones This is a continuation of the previous point, which further explains why this way of thinking and designing software is preferred. @@ -191,8 +181,7 @@ In real-life scenarios, these use cases will be at most rare and uncommon anyway, so it makes sense a custom solution needs to be written. This is why it's important to still provide users the basic building blocks to do it. -#7: Prefer local solutions -~~~~~~~~~~~~~~~~~~~~~~~~~~ +### 7: Prefer local solutions When looking for a solution to a problem, be it implementing a new feature or fixing a bug, sometimes the easiest path is to add data or a new function in the @@ -219,8 +208,7 @@ should be closer to where the problem originates, even if it involves more code, duplicated, more complex or is less efficient. More creativity might be needed, but this path is always the advised one. -#8: Don't use complex canned solutions for simple problems -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +### 8: Don't use complex canned solutions for simple problems Not every problem has a simple solution and, many times, the right choice is to use a third party library to solve the problem. diff --git a/06_community/contributing/04_pr_workflow.md b/06_community/contributing/04_pr_workflow.md index 3944c45..df1b8a3 100644 --- a/06_community/contributing/04_pr_workflow.md +++ b/06_community/contributing/04_pr_workflow.md @@ -1,8 +1,6 @@ -Pull request workflow -===================== - +# Pull request workflow The so-called "PR workflow" used by Pandemonium is common to many projects using Git, and should be familiar to veteran free software contributors. The idea @@ -22,8 +20,7 @@ We will go together through an example to show the typical workflow and associated Git commands. But first, let's have a quick look at the organization of Pandemonium's Git repository. -Git source repository ---------------------- +## Git source repository The `repository on GitHub ( https://github.com/Relintai/pandemonium_engine )` is a `Git ( https://git-scm.com )` code repository together with an embedded @@ -69,8 +66,7 @@ The branches on the Git repository are organized as follows: - There might occasionally be feature branches, usually meant to be merged into the `master` branch at some time. -Forking and cloning -------------------- +## Forking and cloning The first step is to *fork* the `pandemoniumengine/pandemonium ( https://github.com/Relintai/pandemonium_engine )` repository on GitHub. To do so, you will need to have a GitHub account and to @@ -143,8 +139,7 @@ In the following, we will assume as an example that you want to implement a feat Pandemonium's project manager, which is coded in the `editor/project_manager.cpp` file. -Branching ---------- +## Branching By default, the `git clone` should have put you on the `master` branch of your fork (`origin`). To start your own feature development, we will create @@ -189,8 +184,7 @@ you can specify a custom base branch after the new branch's name: $ git checkout -b my-new-feature master ``` -Updating your branch --------------------- +## Updating your branch This would not be needed the first time (just after you forked the upstream repository). However, the next time you want to work on something, you will @@ -254,8 +248,7 @@ Tip: to find the commit ID of the previous state that you would like to restore, and use it as argument of `git reset --hard` to go back to that state. -Making changes --------------- +## Making changes You would then do your changes to our example's `editor/project_manager.cpp` file with your usual development environment @@ -333,8 +326,7 @@ With this, we should have two new commits in our `better-project-manager` branch which were not in the `master` branch. They are still only local though, the remote fork does not know about them, nor does the upstream repo. -Pushing changes to a remote ---------------------------- +## Pushing changes to a remote That's where `git push` will come into play. In Git, a commit is always done in the local repository (unlike Subversion where a commit will modify @@ -357,8 +349,7 @@ Git will ask you for your username and password, and the changes will be sent to your remote. If you check the fork's page on GitHub, you should see a new branch with your added commits. -Issuing a pull request ----------------------- +## Issuing a pull request When you load your fork's branch on GitHub, you should see a line saying *"This branch is 2 commits ahead of pandemoniumengine:master."* (and potentially some @@ -379,8 +370,7 @@ area. You can drag and drop screenshots, GIFs or zipped projects if relevant, to showcase what your work implements. Click "Create a pull request", and tadaa! -Modifying a pull request ------------------------- +## Modifying a pull request While it is reviewed by other contributors, you will often need to make changes to your yet-unmerged PR, either because contributors requested them, @@ -430,8 +420,7 @@ fixes. The above example would then become: -The interactive rebase ----------------------- +## The interactive rebase If you didn't follow the above steps closely to *amend* changes into a commit instead of creating fixup commits, or if you authored your changes without being @@ -530,8 +519,7 @@ And tadaa! Git will happily *replace* your remote branch with what you had locally (so make sure that's what you wanted, using `git log`). This will also update the PR accordingly. -Deleting a Git branch ---------------------- +## Deleting a Git branch After your pull request gets merged, there's one last thing you should do: delete your Git branch for the PR. There won't be issues if you don't delete your branch, but it's diff --git a/06_community/contributing/05_testing_pull_requests.md b/06_community/contributing/05_testing_pull_requests.md index 3687324..35b51eb 100644 --- a/06_community/contributing/05_testing_pull_requests.md +++ b/06_community/contributing/05_testing_pull_requests.md @@ -1,7 +1,6 @@ -Testing pull requests -===================== +# Testing pull requests Many people are developing new features or fixing bugs on GitHub. To help with engine development, you may be asked to test those pull requests @@ -11,8 +10,7 @@ Thanks to GitHub Actions, all `pull requests ( https://github.com/Relintai/pande have continuous builds available. These builds let you try out pull requests without having to compile anything from source. -Downloading a compiled build ----------------------------- +## Downloading a compiled build You can download pull request builds from GitHub Actions. Since only signed in users may download builds directly from GitHub Actions, the procedure varies @@ -27,8 +25,7 @@ Note: `compile the pull request branch from source ( doc_testing_pull_requests_compile )` instead. -If you have a GitHub account -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +#### If you have a GitHub account - Open the pull request page. Click the **Checks** tab near the top of the page: @@ -51,8 +48,7 @@ If you have a GitHub account If you frequently test pull request builds, it may be better to disable Windows SmartScreen or `disable macOS Gatekeeper ( https://disable-gatekeeper.github.io/ )` permanently. -If you don't have a GitHub account -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +#### If you don't have a GitHub account If you don't have a GitHub account and can't sign up for one, you can use the third-party `nightly.link ( https://nightly.link )` service @@ -84,9 +80,7 @@ to generate a universal download link. Windows SmartScreen or `disable macOS Gatekeeper ( https://disable-gatekeeper.github.io/ )` permanently. - -Compiling a pull request branch from source -------------------------------------------- +## Compiling a pull request branch from source This approach may be needed for pull requests that were last updated more than 90 days ago, or to test on platforms and configurations that are not supported diff --git a/06_community/contributing/06_bisecting_regressions.md b/06_community/contributing/06_bisecting_regressions.md index c233844..9a496f1 100644 --- a/06_community/contributing/06_bisecting_regressions.md +++ b/06_community/contributing/06_bisecting_regressions.md @@ -1,7 +1,6 @@ -Bisecting regressions -===================== +# Bisecting regressions Bisecting is a way to find regressions in software. After reporting a bug on the @@ -12,8 +11,7 @@ the regression. Your effort will be widely appreciated :) The guide below explains how to find a regression by bisecting. -What is bisecting? ------------------- +## What is bisecting? Pandemonium developers use the `Git ( https://git-scm.com/ )` version control system. In the context of Git, bisecting is the process of performing a manual @@ -22,8 +20,7 @@ to determine when a regression appeared. While it's typically used for bugs, it can also be used to find other kinds of unexpected changes such as performance regressions. -Using official builds to speed up bisecting -------------------------------------------- +## Using official builds to speed up bisecting Before using Git's `bisect` command, we strongly recommend trying to reproduce the bug with an older (or newer) official release. This greatly reduces the @@ -40,15 +37,13 @@ manage to reproduce the bug with Pandemonium 3.2 beta 1, then try older alpha bu Warning: - For bisecting regressions, don't use patch releases such as Pandemonium 3.1.2. Instead, use the minor version's first release like Pandemonium 3.1. This is because patch releases are built from a separate *stable branch*. This kind of branch doesn't follow the rest of Pandemonium's development, which is done in the `master` branch. -The Git bisect command ----------------------- +## The Git bisect command If you've found a build that didn't exhibit the bug in the above testing process, you can now start bisecting the regression. The Git version control @@ -58,7 +53,6 @@ reproduce the bug. Note: - Before bisecting a regression, you need to set up a build environment to compile Pandemonium from source. To do so, read the `Compiling ( toc-devel-compiling )` page for your target platform. @@ -142,6 +136,5 @@ contributing to Pandemonium :) Note: - You can read the full documentation on `git bisect` `here ( https://git-scm.com/docs/git-bisect )`. diff --git a/06_community/contributing/07_bug_triage_guidelines.md b/06_community/contributing/07_bug_triage_guidelines.md index 1930ba8..f93acb1 100644 --- a/06_community/contributing/07_bug_triage_guidelines.md +++ b/06_community/contributing/07_bug_triage_guidelines.md @@ -1,7 +1,6 @@ -Bug triage guidelines -===================== +# Bug triage guidelines This page describes the typical workflow of the bug triage team aka bugsquad when handling issues and pull requests on Pandemonium's @@ -9,8 +8,7 @@ bugsquad when handling issues and pull requests on Pandemonium's It is bound to evolve together with the bugsquad, so do not hesitate to propose modifications to the following guidelines. -Issues management ------------------ +## Issues management GitHub proposes various features to manage issues: @@ -31,8 +29,7 @@ For the time being, we do not use the project dashboard feature either. As far as possible, we try to assign labels (and milestones, when relevant) to both issues and pull requests. -Labels -~~~~~~ +### Labels The following labels are currently defined in the Pandemonium repository: @@ -146,8 +143,7 @@ If one of the platform labels is used, it is then exclusive and the previous assumption doesn't stand anymore (so if it's a bug on e.g. Android and Linux exclusively, select those two platforms). -Documentation labels -~~~~~~~~~~~~~~~~~~~~ +### Documentation labels In the `documentation repository ( https://github.com/Relintai/pandemonium_engine-docs )`, we use the following labels: @@ -174,8 +170,7 @@ use the following labels: - *Topic:Website*: the issue relates to the Sphinx/Read the Docs frontend or backend, not the documentation contents. -Milestones -~~~~~~~~~~ +### Milestones `Milestones ( https://github.com/Relintai/pandemonium_engine/milestones )` correspond to planned future versions of Pandemonium for which there is an existing roadmap. Issues diff --git a/06_community/contributing/08_code_style_guidelines.md b/06_community/contributing/08_code_style_guidelines.md index eb143cc..9dd0e79 100644 --- a/06_community/contributing/08_code_style_guidelines.md +++ b/06_community/contributing/08_code_style_guidelines.md @@ -1,8 +1,5 @@ - -Code style guidelines -===================== - +# Code style guidelines When contributing to Pandemonium's source code, you will be expected to follow the style guidelines outlined below. Some of them are checked via the Continuous @@ -10,8 +7,7 @@ Integration process and reviewers will ask you to fix potential issues, so best setup your system as outlined below to ensure all your commits follow the guidelines. -C++ and Objective-C -------------------- +## C++ and Objective-C There are no written guidelines, but the code style agreed upon by the developers is enforced via the `clang-format ( http://clang.llvm.org/docs/ClangFormat.html )` @@ -34,6 +30,7 @@ fine. If you plan to contribute regularly however, we strongly advise that you setup clang-format locally to check and automatically fix all your commits. Warning: + Pandemonium's code style should *not* be applied to third-party code, i.e. that is included in Pandemonium's source tree but was not written specifically for our project. Such code usually come from @@ -50,20 +47,17 @@ Warning: See also: - These guidelines only cover code formatting. See `doc_cpp_usage_guidelines` for a list of language features that are permitted in pull requests. -Using clang-format locally -~~~~~~~~~~~~~~~~~~~~~~~~~~ +### Using clang-format locally First of all, you will need to install clang-format. As of now, you need to use **clang-format 13** to be compatible with Pandemonium's format. Later versions might be suitable, but previous versions may not support all used options, or format some things differently, leading to style issues in pull requests. -Installation -^^^^^^^^^^^^ +#### Installation Here's how to install clang-format: @@ -79,8 +73,7 @@ Here's how to install clang-format: You then have different possibilities to apply clang-format to your changes: -Manual usage -^^^^^^^^^^^^ +#### Manual usage You can apply clang-format manually one or more files with the following command: @@ -96,8 +89,7 @@ command: you don't run clang-format on compiled objects (.o and .a files) that are in Pandemonium's tree. So better use `core/*.{cpp,h}` than `core/*`. -Pre-commit hook -^^^^^^^^^^^^^^^ +#### Pre-commit hook For ease of use, we provide a pre-commit hook for Git that will run clang-format automatically on all your commits to check them, and let you apply @@ -111,8 +103,7 @@ If your clang-format is not in the `PATH`, you may have to edit the The hook was tested on Linux and macOS, but should also work in the Git Shell on Windows. -IDE plugin -^^^^^^^^^^ +#### IDE plugin Most IDEs or code editors have beautifier plugins that can be configured to run clang-format automatically, for example each time you save a file. @@ -129,9 +120,7 @@ Here is a non-exhaustive list of beautifier plugins for some IDEs: (Pull requests welcome to extend this list with tested plugins.) - -Header includes -~~~~~~~~~~~~~~~ +### Header includes When adding new C++ or Objective-C files or including new headers in existing ones, the following rules should be followed: @@ -246,16 +235,14 @@ Example: #include ``` -Java ----- +## Java Pandemonium's Java code (mostly in `platform/android`) is also enforced via `clang-format`, so see the instructions above to set it up. Keep in mind that this style guide only applies to code written and maintained by Pandemonium, not third-party code such as the `java/src/com/google` subfolder. -Python ------- +## Python Pandemonium's SCons buildsystem is written in Python, and various scripts included in the source tree are also using Python. @@ -263,14 +250,12 @@ in the source tree are also using Python. For those, we follow the `Black style guide ( https://github.com/psf/black#the-black-code-style )`. Blacken your Python changes using `Black ( https://pypi.org/project/black/ )`. -Using black locally -~~~~~~~~~~~~~~~~~~~ +### Using black locally First of all, you will need to install black. Black requires Python 3.6.0+ to run. -Installation -^^^^^^^^^^^^ +#### Installation Here's how to install black: @@ -280,8 +265,7 @@ Here's how to install black: You then have different possibilities to apply black to your changes: -Manual usage -^^^^^^^^^^^^ +#### Manual usage You can apply `black` manually to one or more files with the following command: @@ -295,8 +279,7 @@ command: - The path can point to several files, either one after the other or using wildcards like in a typical Unix shell. -Pre-commit hook -^^^^^^^^^^^^^^^ +#### Pre-commit hook For ease of use, we provide a pre-commit hook for Git that will run black automatically on all your commits to check them, and let you apply @@ -306,15 +289,13 @@ This "hook" is a script which can be found in `misc/hooks`. Refer to that folder's `README.md` for installation instructions. -Editor integration -^^^^^^^^^^^^^^^^^^ +#### Editor integration Many IDEs or code editors have beautifier plugins that can be configured to run black automatically, for example each time you save a file. For details you can check `Black editor integration ( https://github.com/psf/black#editor-integration )`. -Comment style guide -------------------- +## Comment style guide This comment style guide applies to all programming languages used within Pandemonium's codebase. diff --git a/06_community/contributing/09_cpp_usage_guidelines.md b/06_community/contributing/09_cpp_usage_guidelines.md index 34a80c5..6cb4b7b 100644 --- a/06_community/contributing/09_cpp_usage_guidelines.md +++ b/06_community/contributing/09_cpp_usage_guidelines.md @@ -1,10 +1,7 @@ +# C++ usage guidelines -C++ usage guidelines -==================== - -Rationale ---------- +## Rationale Since Pandemonium 4.0, the C++ standard used throughout the codebase is a subset of **C++17**. While modern C++ brings a lot of opportunities to write faster, more @@ -39,16 +36,14 @@ See also: See `doc_code_style_guidelines` for formatting guidelines. -Disallowed features -------------------- +## Disallowed features **Any feature not listed below is allowed.** Using features like `constexpr` variables and `nullptr` is encouraged when possible. Still, try to keep your use of modern C++ features conservative. Their use needs to serve a real purpose, such as improving code readability or performance. -Standard Template Library -^^^^^^^^^^^^^^^^^^^^^^^^^ +#### Standard Template Library We don't allow using the `STL ( https://en.wikipedia.org/wiki/Standard_Template_Library )` as Pandemonium provides its own data types (among other things). @@ -64,13 +59,11 @@ This means that pull requests should **not** use `std::string`, Note: - Pandemonium also has a List datatype (which is a linked list). While List is already used in the codebase, it typically performs worse than other datatypes like Vector and Array. Therefore, List should be avoided in new code unless necessary. -`auto` keyword -^^^^^^^^^^^^^^^^ +#### `auto` keyword Please don't use the `auto` keyword for type inference. While it can avoid repetition, it can also lead to confusing code: @@ -90,21 +83,18 @@ pull requests. We chose to forbid `auto` instead of allowing it on a case-by-case basis to avoid having to decide on difficult edge cases. Thank you for your understanding. -Lambdas -^^^^^^^ +#### Lambdas Lambdas should be used conservatively when they make code effectively faster or simpler, and do not impede readability. Please ask before using lambdas in a pull request. -`#pragma once` directive -^^^^^^^^^^^^^^^^^^^^^^^^^^ +#### `#pragma once` directive To follow the existing style, please use standard `#ifdef`-based include guards instead of `#pragma once` in new files. See also: - See `doc_code_style_guidelines_header_includes` for guidelines on sorting includes in C++ and Objective-C files. diff --git a/06_community/contributing/10_content_guidelines.md b/06_community/contributing/10_content_guidelines.md index 29c4a9c..a3dd6c0 100644 --- a/06_community/contributing/10_content_guidelines.md +++ b/06_community/contributing/10_content_guidelines.md @@ -1,7 +1,5 @@ - -Content guidelines -================== +# Content guidelines This document is here to help us assess what we should include in the official documentation. Below, you will find a couple of principles and recommendations @@ -15,15 +13,13 @@ We want to achieve two goals: programming foundations. Instead, we should provide a reference for how Pandemonium's features work. -Guidelines and principles -------------------------- +## Guidelines and principles Below are the guidelines we should strive to follow. They are not hard rules, though: exceptionally, a topic will require breaking one or more of these. Still, we should strive to achieve the two goals listed above. -Writing complete and accessible documentation -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +### Writing complete and accessible documentation **A feature doesn't exist unless it is documented**. If a user can't find information about a feature and how it works, it doesn't exist to them. We @@ -31,7 +27,6 @@ should ensure that we cover everything Pandemonium does. Note: - When adding or updating an engine feature, the documentation team needs to know about it. Contributors should open an issue on the `pandemonium-docs` repository when their work gets merged and requires documentation. @@ -49,7 +44,6 @@ second title makes it clear what the purpose of signals is. Note: - Long section titles lead to long entries in the side menu, which can make navigation cumbersome. Try to keep headings five words long or less. @@ -58,8 +52,7 @@ link it to the corresponding documentation. For instance, a page about physics may use signals, in which case we could note that the page that introduces signals is a pre-requisite. -Limiting cognitive load -~~~~~~~~~~~~~~~~~~~~~~~ +### Limiting cognitive load Limit the cognitive load required to read the documentation. The simpler and more explicit language we use, the more efficient it becomes for people to @@ -87,7 +80,6 @@ practice explaining the feature before writing about it. Note: - Having programming foundations is a pre-requisite to use a complex engine like Pandemonium. Talking about variables, functions, or classes is acceptable. But we should favor plain language over specific terminology like diff --git a/06_community/contributing/11_building_the_manual.md b/06_community/contributing/11_building_the_manual.md index 944d34c..84b25a5 100644 --- a/06_community/contributing/11_building_the_manual.md +++ b/06_community/contributing/11_building_the_manual.md @@ -1,7 +1,6 @@ -Building the manual with Sphinx -=============================== +# Building the manual with Sphinx This page explains how to build a local copy of the Pandemonium manual using the Sphinx docs engine. This allows you to have local HTML files and build the @@ -87,10 +86,11 @@ You can also specify a list of files to build, which can greatly speed up compil .. code:: sh +``` sphinx-build -b html ./ _build classes/class_node.rst classes/class_resource.rst +``` -Building with Sphinx and virtualenv ------------------------------------ +## Building with Sphinx and virtualenv If you want your Sphinx installation scoped to the project, you can install sphinx-build using virtualenv. To do so, run this command from this repository's @@ -98,8 +98,10 @@ root folder: .. code:: sh +``` virtualenv --system-site-packages env/ . env/bin/activate pip3 install -r requirements.txt +``` Then, run `make html` as shown above. diff --git a/06_community/contributing/12_updating_the_class_reference.md b/06_community/contributing/12_updating_the_class_reference.md index bce9279..424238e 100644 --- a/06_community/contributing/12_updating_the_class_reference.md +++ b/06_community/contributing/12_updating_the_class_reference.md @@ -1,7 +1,5 @@ - -Contributing to the class reference -=================================== +# Contributing to the class reference The class reference is available online in the `classes ( toc-class-ref )` @@ -19,7 +17,6 @@ taking care of a given class. See also: - You can find the writing guidelines for the class reference `here ( doc_class_reference_writing_guidelines )`. For details on Git usage and the pull request workflow, please @@ -62,8 +59,7 @@ Warning: scripts as described in `doc_class_reference_writing_guidelines_editing_xml`. -Updating the documentation template -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +### Updating the documentation template When you create a new class or modify the engine's API, you need to re-generate the XML files in `doc/classes/`. diff --git a/06_community/contributing/13_class_reference_writing_guidelines.md b/06_community/contributing/13_class_reference_writing_guidelines.md index 9277a5f..178cad1 100644 --- a/06_community/contributing/13_class_reference_writing_guidelines.md +++ b/06_community/contributing/13_class_reference_writing_guidelines.md @@ -1,7 +1,5 @@ - -Class reference writing guidelines -================================== +# Class reference writing guidelines This page explains how to write the class reference. You will learn where to write new descriptions for the classes, methods, and properties for Pandemonium's @@ -9,7 +7,6 @@ built-in node types. See also: - To learn to submit your changes to the Pandemonium project using the Git version control system, see `doc_updating_the_class_reference`. @@ -84,10 +81,7 @@ Write in a clear and simple language. Always follow the `writing guidelines **Do not leave empty lines** in the descriptions: each line in the XML file will result in a new paragraph, even if it is empty. - - -How to edit class XML ---------------------- +## How to edit class XML Edit the file for your chosen class in `doc/classes/` to update the class reference. The folder contains an XML file for each class. The XML lists the @@ -115,47 +109,30 @@ We recommend using a code editor that supports XML files like Vim, Atom, Visual Notepad++, or another to comfortably edit the file. You can also use their search feature to find classes and properties quickly. - - -Improve formatting with BBCode style tags -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +### Improve formatting with BBCode style tags Pandemonium's class reference supports BBCode-like tags. They add nice formatting to the text. Here's the list of available tags: -+----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ + | Tag | Effect | Usage | Result | -+============================+======================================+===================================+===================================================+ -| [Class] | Link a class | Move the [Sprite]. | Move the `Sprite`. | -+----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ -| [method methodname] | Link to a method in this class | Call [method hide]. | Call `hide`. | -+----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ -| [method Class.methodname] | Link to another class's method | Call [method Spatial.hide]. | Call `hide`. | -+----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ -| [member membername] | Link to a member in this class | Get [member scale]. | Get `scale`. | -+----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ -| [member Class.membername] | Link to another class's member | Get [member Node2D.scale]. | Get `scale`. | -+----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ -| [signal signalname] | Link to a signal in this class | Emit [signal renamed]. | Emit `renamed`. | -+----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ -| [signal Class.signalname] | Link to another class's signal | Emit [signal Node.renamed]. | Emit `renamed`. | -+----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ +|----------------------------|--------------------------------------|-----------------------------------|---------------------------------------------------| +| [Class] | Link a class | Move the [Sprite]. | Move the `Sprite`. | +| [method methodname] | Link to a method in this class | Call [method hide]. | Call `hide`. | +| [method Class.methodname] | Link to another class's method | Call [method Spatial.hide]. | Call `hide`. | +| [member membername] | Link to a member in this class | Get [member scale]. | Get `scale`. | +| [member Class.membername] | Link to another class's member | Get [member Node2D.scale]. | Get `scale`. | +| [signal signalname] | Link to a signal in this class | Emit [signal renamed]. | Emit `renamed`. | +| [signal Class.signalname] | Link to another class's signal | Emit [signal Node.renamed]. | Emit `renamed`. | | [b] [/b] | Bold | Some [b]bold[/b] text. | Some **bold** text. | -+----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ | [i] [/i] | Italic | Some [i]italic[/i] text. | Some *italic* text. | -+----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ -| [code] [/code] | Monospace | Some [code]monospace[/code] text. | Some `monospace` text. | -+----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ +| [code] [/code] | Monospace | Some [code]monospace[/code] text. | Some `monospace` text. | | [kbd] [/kbd] | Keyboard/mouse shortcut | Some [kbd]Ctrl + C[/kbd] key. | Some :kbd:`Ctrl + C` key. | -+----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ | [codeblock] [/codeblock] | Multiline preformatted block | *See below.* | *See below.* | -+----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ | [codeblocks] [/codeblocks] | [codeblock] for multiple languages | *See below.* | *See below.* | -+----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ | [gdscript] [/gdscript] | GDScript codeblock tab in codeblocks | *See below.* | *See below.* | -+----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ | [csharp] [/csharp] | C# codeblock tab in codeblocks | *See below.* | *See below.* | -+----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+ + Use `[codeblock]` for pre-formatted code blocks. Inside `[codeblock]`, always use **four spaces** for indentation. The parser will delete tabs. For @@ -236,8 +213,7 @@ Notice the use of italics instead of bold: In all the paragraphs described above, make sure the punctuation is part of the BBCode tags for consistency. -I don't know what this method does! -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +### I don't know what this method does! No problem. Leave it behind, and list the methods you skipped when you request a pull of your changes. Another writer will take care of it. diff --git a/06_community/contributing/14_editor_and_docs_localization.md b/06_community/contributing/14_editor_and_docs_localization.md index 726bd99..d34ccf1 100644 --- a/06_community/contributing/14_editor_and_docs_localization.md +++ b/06_community/contributing/14_editor_and_docs_localization.md @@ -1,7 +1,6 @@ -Editor and docs localization -============================ +# Editor and docs localization Pandemonium aims to make game development available to everyone, including people who may not know or be comfortable with English. Therefore, we do our best to make @@ -29,14 +28,13 @@ localization of images. Tip: - Translating all the official Pandemonium content is a massive undertaking, so we advise prioritizing the resources as they are listed above: first the editor interface, then the online documentation, and eventually the class reference if there are enough translators to keep up with updates. -Using Weblate for translations ------------------------------- +## Using Weblate for translations + While our translations eventually reside in the Git repositories of the Pandemonium engine and its documentation, all translation updates are handled through @@ -60,8 +58,7 @@ See also: workflow ( https://docs.weblate.org/en/latest/user/translating.html )` for more details. -Adding a new language -^^^^^^^^^^^^^^^^^^^^^ +#### Adding a new language If your language is already listed, click on its name to access the overview, and skip the rest of this section. @@ -72,7 +69,7 @@ to translate to: ![](img/l10n_02_new_translation.png) -.. important:: +Important: If your language is spoken in several countries with only limited regional variations, please consider adding it with its generic variant (e.g. `fr` @@ -93,8 +90,7 @@ to translate to: `es_ES`, `es_MX`, etc. if necessary) or Portuguese (`pt_BR` vs `pt_PT`). -Translation interface -^^^^^^^^^^^^^^^^^^^^^ +#### Translation interface Once a language has been selected, you will see an overview of the translation status, including how many strings are left to translate or review. Each item @@ -139,8 +135,7 @@ On that page, you have: original string on GitHub. You may need to search for the string in the page to locate it and its surrounding context. -Locating original content -------------------------- +### Locating original content PO files are an ordered list of source strings (`msgid`) and their translation (`msgstr`), and by default, Weblate will present the strings in that order. It @@ -148,7 +143,7 @@ can therefore be useful to understand how the content is organized in the PO files to help you locate the original content and use it as a reference when translating. -.. important:: +Important: It is primordial to use the original context as reference when translating, as many words have several possible translations depending on the context. @@ -192,7 +187,6 @@ used with the `location:` token, e.g. `location:nodes_and_scenes.rst`): Note: - When a given source string is used in multiple source locations, they will all be concatenated into one. For example, the above `location:nodes_and_scenes.rst` query would land first on the @@ -203,15 +197,13 @@ Note: So it may happen that a given paragraph or section title is not at the location you'd expect it when reading the online version of a page. -Respecting the markup syntax ----------------------------- +## Respecting the markup syntax Each translation resource originates from a different source code format, and having some notions on the markup language used for each resource is important to avoid creating syntax errors in your translations. -Editor interface (C++) -^^^^^^^^^^^^^^^^^^^^^^ +#### Editor interface (C++) The editor translations originate from C++ strings, and may use: @@ -249,8 +241,7 @@ Note: Only logical order of the characters matters, in the right-to-left text, format specifiers may be displayed as `s%`. -Online documentation (RST) -^^^^^^^^^^^^^^^^^^^^^^^^^^ +#### Online documentation (RST) The documentation translations originate from reStructuredText (RST) files, which also use their own markup syntax to style text, create internal and @@ -302,8 +293,7 @@ See also: You may encounter especially the inline markup (bold, italics, inline code) and the internal and external hyperlink markup. -Class reference (BBCode) -^^^^^^^^^^^^^^^^^^^^^^^^ +#### Class reference (BBCode) The class reference is documented in the main Pandemonium repository using XML files, and with BBCode-like markup for styling and internal references. @@ -334,13 +324,11 @@ breaks if they are not part of the original translation. See also: - See our documentation for class reference writers for the `list of BBCode-like tags ( doc_class_reference_writing_guidelines_bbcode )` which are used throughout the class reference. -Offline translation and testing -------------------------------- +## Offline translation and testing While we advise using the Weblate interface to write translations, you also have the possibility to download the PO file locally to translate it with your @@ -358,7 +346,6 @@ upload mode. Note: - If a significant amount of time has passed between your download of the PO file and the upload of the edited version, there is a risk to overwrite the translations authored by other contributors in the meantime. This is why we @@ -376,8 +363,7 @@ You can also test class reference changes the same way by renaming the PO file similarly and placing it in the `doc/translations/` folder (`GitHub ( https://github.com/Relintai/pandemonium_engine/tree/master/doc/translations )`). -Localizing documentation images -------------------------------- +## Localizing documentation images The online documentation includes many images, which can be screenshots of the Pandemonium editor, custom-made graphs, of any other kind of visual content. Some of @@ -389,7 +375,6 @@ documentation translations are synced from Weblate. Note: - The workflow is not the most straightforward and requires some knowledge of Git. We plan to work on a simplified Web tool which could be used to manage image localization in a convenient way, abstracting away these steps. diff --git a/06_community/contributing/15_contributing_to_the_documentation.md b/06_community/contributing/15_contributing_to_the_documentation.md index e2f0969..b0f541b 100644 --- a/06_community/contributing/15_contributing_to_the_documentation.md +++ b/06_community/contributing/15_contributing_to_the_documentation.md @@ -1,19 +1,15 @@ - -Contributing to the documentation -================================= +# Contributing to the documentation This guide explains how to contribute to Pandemonium's documentation, be it by writing or reviewing pages. See also: - If you want to translate pages or the class reference from English to other languages, read `doc_editor_and_docs_localization`. -Getting started ---------------- +## Getting started To modify or create pages in the reference manual, you need to edit `.rst` files in the `pandemonium-docs GitHub repository @@ -34,8 +30,7 @@ Warning: methods, or properties, read `doc_updating_the_class_reference`. -What is the Pandemonium documentation -------------------------------- +## What is the Pandemonium documentation The Pandemonium documentation is intended as a comprehensive reference manual for the Pandemonium game engine. It is not meant to contain step-by-step tutorials, except for @@ -49,8 +44,7 @@ contribute, you should also read: 2. The content guidelines. They explain the principles we follow to write the documentation and the kind of content we accept. -Contributing changes --------------------- +## Contributing changes **Pull Requests should use the** `master` **branch by default.** Only make Pull Requests against other branches (e.g. `2.1` or `3.0`) if your changes only @@ -60,8 +54,7 @@ Though less convenient to edit than a wiki, this Git repository is where we write the documentation. Having direct access to the source files in a revision control system is a plus to ensure our documentation quality. -Editing existing pages -~~~~~~~~~~~~~~~~~~~~~~ +### Editing existing pages To edit an existing page, locate its `.rst` source file and open it in your favorite text editor. You can then commit the changes, push them to your fork, @@ -74,8 +67,7 @@ See also: To build the manual and test changes on your computer, see `doc_building_the_manual`. -Editing pages online --------------------- +## Editing pages online You can edit the documentation online by clicking the **Edit on GitHub** link in the top-right of every page. @@ -102,8 +94,7 @@ and to log in to use it. Once logged in, you can propose change like so: Another contributor will review your changes and merge them into the docs if they're good. They may also make changes or ask you to do so before merging. -Adding new pages ----------------- +## Adding new pages Before adding a new page, please ensure that it fits in the documentation: @@ -120,8 +111,7 @@ You should then add your page to the relevant "toctree" (table of contents, e.g. `tutorials/3d/index.rst`). Add your new filename to the list on a new line, using a relative path and no extension, e.g. here `light_baking`. -Titles -~~~~~~ +### Titles Always begin pages with their title and a Sphinx reference name: @@ -144,8 +134,7 @@ Write your titles like plain sentences, without capitalizing each word: Only propers nouns, projects, people, and node class names should have their first letter capitalized. -Sphinx and reStructuredText syntax -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +### Sphinx and reStructuredText syntax Check Sphinx’s `reST Primer ( https://www.sphinx-doc.org/en/stable/rest.html )` and the `official reference ( http://docutils.sourceforge.net/rst.html )` for @@ -161,8 +150,7 @@ how to use Sphinx directives like `Note: the `Sphinx directives documentation ( https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html )`. -Adding images and attachments -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +### Adding images and attachments To add images, please put them in an `img/` folder next to the `.rst` file with a meaningful name and include them in your page with: @@ -179,8 +167,7 @@ using this inline markup: :download:`myfilename.zip ( files/myfilename.zip )` ``` -License -------- +## License This documentation and every page it contains is published under the terms of the `Creative Commons Attribution 3.0 license (CC-BY-3.0) diff --git a/06_community/contributing/16_docs_writing_guidelines.md b/06_community/contributing/16_docs_writing_guidelines.md index dda8053..26035f5 100644 --- a/06_community/contributing/16_docs_writing_guidelines.md +++ b/06_community/contributing/16_docs_writing_guidelines.md @@ -1,7 +1,6 @@ -Docs writing guidelines -======================= +# Docs writing guidelines The Pandemonium community is rich and international. Users come from all around the world. Some of them are young, and many aren't native English @@ -28,22 +27,18 @@ There are 3 rules to describe classes: Note: - A technical writer's job is to pack as much information as possible into the smallest and clearest sentences possible. These guidelines will help you work towards that goal. See also: - See the `content guidelines ( doc_content_guidelines )` for information on the types of documentation you can write in the official documentation. -7 rules for clear English -------------------------- +## 7 rules for clear English -Use the active voice -~~~~~~~~~~~~~~~~~~~~ +### Use the active voice Use the active voice when possible. Take the classes, methods, and constants you describe as the subject. It's natural to write using the @@ -75,8 +70,7 @@ Active: [...] Only some Node2Ds **implement** this method. ``` -Use precise action verbs -~~~~~~~~~~~~~~~~~~~~~~~~ +### Use precise action verbs Favor precise yet common verbs over generic ones like `make`, `set`, and any expression you can replace with a single word. @@ -97,8 +91,7 @@ like `place`, `position`, `rotate`, `fade`, etc. Position the node's pivot to the [code]pivot[/code] value. [...] ``` -Avoid verbs that end in -ing -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +### Avoid verbs that end in -ing The progressive forms describe continuous actions. E.g. "is calling", "is moving". @@ -130,8 +123,7 @@ Tip: conjugation, so you may use them: `the remaining movement`, `the missing file`, etc. -Remove unnecessary adverbs and adjectives -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +### Remove unnecessary adverbs and adjectives Write as few adjectives and adverbs as possible. Only use them if they add key information to the description. @@ -149,8 +141,7 @@ documentation but don't add any information: A big texture [...] ``` -Ban these 8 words -~~~~~~~~~~~~~~~~~ +### Ban these 8 words **Don't** ever use these 8 banned words: @@ -215,8 +206,7 @@ on the Timer node's page: Provides essential math functions to manipulate 3D vectors: cross product, normalize, rotate, etc. ``` -Use explicit references -~~~~~~~~~~~~~~~~~~~~~~~ +### Use explicit references Favor explicit references over implicit ones. @@ -236,8 +226,7 @@ the most common in English, and they require you to check the reference. If you need to repeat the same variable name 3 or 4 times, you probably need to rephrase your description. -Use 's to show possession -~~~~~~~~~~~~~~~~~~~~~~~~~ +### Use 's to show possession Avoid "The milk **of** the cow". It feels unnatural in English. Write "The cow's milk" instead. @@ -255,8 +244,7 @@ sentence, and keep it short: The **AtlasTexture's** used region. ``` -Use the Oxford comma to enumerate anything -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +### Use the Oxford comma to enumerate anything From the Oxford dictionary: @@ -279,11 +267,9 @@ element of a list with more than two elements. Create a KinematicBody2D node, a CollisionShape2D node, and a sprite node. ``` -How to write methods and classes --------------------------------- +## How to write methods and classes -Dynamic vs static typing -~~~~~~~~~~~~~~~~~~~~~~~~ +### Dynamic vs static typing The code examples in the documentation should follow a consistent style not to confuse users. As static type hints are an optional feature of GDScript, we @@ -332,8 +318,7 @@ The exception is topics that explain static typing concepts to users. return arguments[choice] ``` -Use real-world code examples where appropriate -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +### Use real-world code examples where appropriate Real-world examples are more accessible to beginners than abstract `foos` and `bars`. You can also copy them directly from your game projects, ensuring that @@ -370,8 +355,7 @@ Of course, there are times when using real-world examples is impractical. In those situations, you should still avoid using names such as `my_var`, `foo()` or `my_func()` and consider more meaningful names for your examples. -Give an overview of the node in the brief description -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +### Give an overview of the node in the brief description The brief description is the reference's most important sentence. It's the user's first contact with a node: @@ -399,8 +383,7 @@ functionality, in up to 200 characters. Use the node's full description to provide more information, and a code example, if possible. -Mention what methods return if it's useful -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +### Mention what methods return if it's useful Some methods return important values. Describe them at the end of the description, ideally on a new line. No need to mention the return values @@ -424,8 +407,7 @@ Notice the exception to the "direct voice" rule: with the move method, an external collider can influence the method and the body that calls `move`. In this case, you can use the passive voice. -Use "if true" to describe booleans -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +### Use "if true" to describe booleans For boolean member variables, always use `if true` and/or `if false`, to stay explicit. `Controls whether or not` may be @@ -440,8 +422,7 @@ Also, surround boolean values, variable names and methods with `[code][/code]`. If [code]true[/code], the timer will automatically start when entering the scene tree. ``` -Use `[code]` around arguments -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +### Use `[code]` around arguments In the class reference, always surround arguments with `[code][/code]`. In the documentation and in Pandemonium, it will display like `this`. When you edit XML @@ -449,18 +430,16 @@ files in the Pandemonium repository, replace existing arguments written like 'th \`this\` with `[code]this[/code]`. -Common vocabulary to use in Pandemonium's documentation -------------------------------------------------- +## Common vocabulary to use in Pandemonium's documentation The developers chose some specific words to refer to areas of the interface. They're used in the sources, in the documentation, and you should always use them instead of synonyms, so the users know what you're talking about. -.. figure:: img/editor-vocabulary-overview.png) - :alt: Overview of the interface and common vocabulary +![](img/editor-vocabulary-overview.png) - Overview of the interface and common vocabulary +Overview of the interface and common vocabulary In the top left corner of the editor lie the `main menus`. In the center, the buttons change the `workspace`. And together the buttons @@ -483,8 +462,7 @@ class names, which you can't fold, are `Classes` e.g. the `properties`. E.g. `position` or `modulate color` are both `properties`. -Keyboard shortcut guidelines ----------------------------- +## Keyboard shortcut guidelines Keyboard and mouse shortcuts should make use of the `:kbd:` tag, which allows shortcuts to stand out from the rest of the text and inline code. Use the @@ -498,12 +476,11 @@ On macOS, `Cmd` often replaces `Ctrl` in keyboard shortcuts. Try to integrate the shortcut into sentences the best you can. Here are some examples with the `:kbd:` tag left as-is for better visibility: -- Press `:kbd:`Ctrl + Alt + T``` to toggle the panel (`:kbd:`Cmd + Alt + T``` on macOS). -- Press `:kbd:`Space``` and hold the left mouse button to pan in the 2D editor. -- Press `:kbd:`Shift + Up Arrow``` to move the node upwards by 8 pixels. +- Press `:kbd:` `Ctrl + Alt + T` to toggle the panel (`:kbd:` `Cmd + Alt + T` on macOS). +- Press `:kbd:` `Space` and hold the left mouse button to pan in the 2D editor. +- Press `:kbd:` `Shift + Up Arrow` to move the node upwards by 8 pixels. -Image contribution guidelines ------------------------------ +## Image contribution guidelines A significant part of the documentation is images, and there are several important guidelines to follow. diff --git a/06_community/contributing/17_documentation_guidelines.md b/06_community/contributing/17_documentation_guidelines.md index 86f3356..757d3fa 100644 --- a/06_community/contributing/17_documentation_guidelines.md +++ b/06_community/contributing/17_documentation_guidelines.md @@ -1,7 +1,6 @@ -Documentation guidelines -======================== +# Documentation guidelines This page describes the rules to follow if you want to contribute to Pandemonium Engine by writing or reviewing documentation, or by translating existing @@ -10,8 +9,7 @@ documentation. Also, have a look at README of the and the `docs front page ( https://docs.pandemoniumengine.org )` on what steps to follow and how to contact the docs team. -How to contribute ------------------ +## How to contribute Creating or modifying documentation pages is mainly done via the `pandemonium-docs GitHub repository ( https://github.com/Relintai/pandemonium_engine-docs )`. @@ -41,8 +39,7 @@ Warning: in-editor documentation as well as the API reference of the online docs. Read more here: `doc_updating_the_class_reference`. -The 'Edit on GitHub' link -------------------------- +## The 'Edit on GitHub' link If you're reading documentation on `docs.pandemoniumengine.org ( https://docs.pandemoniumengine.org )`, you'll see an **Edit on GitHub** hyperlink at the top right of the page. @@ -68,8 +65,7 @@ reading as follows: they're acceptable. You might also be asked to make modifications to your changes before they're included. -What makes good documentation? ------------------------------- +## What makes good documentation? Documentation should be well written in plain English, using well-formed sentences and various levels of sections and subsections. It should be clear @@ -89,8 +85,7 @@ definitions: You are free to write the kind of documentation you wish, as long as you respect the following rules (and the ones on the repo). -Titles ------- +## Titles Always begin pages with their title and a Sphinx reference name: @@ -116,8 +111,7 @@ And this is a bad example: Only project, people and node class names should have capitalized first letter. -Translating existing pages --------------------------- +## Translating existing pages You can help to translate the official Pandemonium documentation on our `Hosted Weblate ( https://hosted.weblate.org/engage/pandemonium-engine/ )`. @@ -132,8 +126,7 @@ There also is the official `Pandemonium i18n repository ( https://github.com/Relintai/pandemonium_engine-docs-l10n )` where you can see when the data was last synchronized. -License -------- +## License This documentation and every page it contains is published under the terms of the `Creative Commons Attribution 3.0 license (CC-BY-3.0) ( https://tldrlegal.com/license/creative-commons-attribution-(cc) )`, with attribution to "Péter Magyar and the Pandemonium community, and Juan Linietsky, Ariel Manzur and the Godot community".