Last active
May 7, 2023 11:36
-
-
Save aliustaoglu/1e9c2a013efd5cafb46ddb0905c5f658 to your computer and use it in GitHub Desktop.
BabylonGD Documentation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
<p>This extension is intended to transform classic top-down 2D games created in GDevelop into 3D games, using Babylon.js to achieve this. However, it is not compatible with side-view platform games. | |
</p> | |
<p>Thinking in 2D is typically easier than thinking in 3D, but 3D games are often considered cooler (although this is debatable!). This extension is designed to enable the creation of cool games with ease. | |
</p> | |
<p>It's worth noting that this extension is highly opinionated and aims to minimise the use of events or actions unless absolutely necessary. It seeks to achieve everything using behaviours wherever possible. As it is still in its early stages, I cannot recommend using it for anything other than fun or game jams. Furthermore, I cannot guarantee backward compatibility, and anything may break in the next version, so use it at your own risk. | |
</p> | |
<p>Please note that I do not own any of the assets used in the demo project. As I distribute the project, I always use CC0 assets. However, if you notice any mistakes, please let me know so that I can take action as soon as possible. If you plan to use these assets in your own projects, please check their licences from the provided links. | |
</p> | |
<p>As this is not my main project, I cannot guarantee frequent updates. I have another project that uses a different engine, which takes up most of my time. However, since I enjoy working with Babylon.js and GDevelop, I am planning to add new features and release new versions as and when I can. | |
</p> | |
<p><strong>EXPERIMENTAL PREVIEW BUILD</strong><br></p> | |
<p>This is the initial release of the extension. Very premature release for GDevelop 3D Jam. I'll probably make big changes including removing behaviors and adding new ones. So, please keep this in mind while using this extension.</p> | |
<p><strong>DOCUMENTATION</strong></p> | |
<p></p> | |
<div title="header"><p style="line-height: 100%; margin-bottom: 0.47in"> | |
<span lang="en-US">BabylonGD: GDevelop in 3D (Extension) v0.0.1</span></p> | |
</div> | |
<h1 class="western" align="justify"><strong>Getting Started</strong></h1> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in"><br> | |
<br> | |
</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in">To | |
download the extension, go to | |
<u><a href="https://aliustaoglu.itch.io/babylongd-gdevelop-in-3d">https://aliustaoglu.itch.io/babylongd-gdevelop-in-3d</a></u></p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in">Please | |
note that this extension is neither an official nor a community one, | |
and therefore, it needs to be installed manually. To install the | |
extension, follow these steps:</p> | |
<ul> | |
<li><p align="justify" style="line-height: 108%; margin-bottom: 0.11in"> | |
Click on “Create or search for new extensions”.</p> | |
</li><li><p align="justify" style="line-height: 108%; margin-bottom: 0.11in"> | |
Click on “Import extension”.</p> | |
</li><li><p align="justify" style="line-height: 108%; margin-bottom: 0.11in"> | |
Select the extension that you have downloaded.</p> | |
</li></ul> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in"><img src="BabylonGD_html_32c21d860e814216.png" name="Picture 1" align="bottom" width="601" height="395" border="0"> | |
</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in">To | |
activate the extension, you need to add a camera and use below event.</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in"><img src="BabylonGD_html_9b3052941c12af4c.png" name="Image2" align="bottom" width="602" height="258" border="0"> | |
</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in">Then | |
your scene should have one camera object for the changes to take | |
place.</p> | |
<h1 class="western" align="justify"><strong>Behaviours</strong></h1> | |
<h2 class="western" align="justify"><strong>Camera Behaviour</strong></h2> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in">This | |
is the required behaviour. All scenes should have one (and only one) | |
object that has this behaviour. | |
</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in"><u>Properties</u></p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in"><strong>hide</strong>: | |
Whether it should be hidden in 3D scene. You usually want to hide. | |
Enable only if you want to debug.</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in"><strong>checkCollisions</strong>: | |
Whether camera should have a collider around it. If enabled camera | |
won’t be able to move when collided with other objects, such as | |
structures.</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in"><strong>applyGravity</strong>: | |
Whether gravity should be applied to camera. If applied, built-in | |
Babylon.js physics will be applied. CANNON or Havok is not supported | |
yet.</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in"><strong>cameraType</strong>: | |
Choose a camera type. Currently only FPS camera is supported. Other | |
camera types will be added in the future.</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in"><strong>keysUp</strong>: | |
By default, W in WASD movement. Override if you want to change.</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in"><strong>keysDown</strong>: | |
By default, S in WASD movement. Override if you want to change.</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in"><strong>keysLeft</strong>: | |
By default, A in WASD movement. Override if you want to change.</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in"><strong>keysRight</strong>: | |
By default, D in WASD movement. Override if you want to change.</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in"><br> | |
<br> | |
</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in"><u>Actions</u></p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in"><strong>setZOrder</strong>: | |
Change the z-order of the camera. This is typically the third | |
dimension what makes it a 3D game. In Babylon.js it’s the Y axis | |
but since (X, Y) is what GDevelop uses, the extension will do the | |
translation in the background.</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in"><strong>applyGravity</strong>: | |
You can change initial behaviour property.</p> | |
<h2 class="western" align="justify"><br> | |
</h2> | |
<h2 class="western" align="justify"><strong>Structure Behaviour</strong></h2> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in">This | |
will create a box consisting of 6 planes. For each plane you can | |
assign a texture. So other than behaviour properties, you will need | |
to create sprite animations with below names:</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in">FRONT, | |
LEFT, RIGHT, BOTTOM, TOP, BOTTOM</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in">All | |
self-explanatory but FRONT and LEFT animations are compulsory. If you | |
don’t provide RIGHT, Then LEFT will be used. For all the rest if | |
you don’t provide a texture FRONT texture will be used.</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in"><img src="BabylonGD_html_ef4c877b56e6a3c9.png" name="Picture 3" align="bottom" width="601" height="613" border="0"> | |
</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in">You | |
can provide multiple textures for each animation. Then it will be an | |
“animation” like GDevelop in 2D.</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in"><br> | |
<br> | |
</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in">If | |
the object is bigger than the texture, then the extension needs to | |
know how it will handle it. It can repeat (tile) the texture or | |
extend it. You can use below behaviour properties to achieve this.</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in"><img src="BabylonGD_html_743275ef6543a033.png" name="Picture 4" align="bottom" width="441" height="240" border="0"> | |
</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in">And | |
since GDevelop canvas is 2D-only, we need to let Babylon.js know | |
about the depth of the building. Need to add a variable named “depth” | |
for this.</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in"><img src="BabylonGD_html_765863041593612a.png" name="Picture 5" align="bottom" width="601" height="219" border="0"> | |
</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in"><img src="BabylonGD_html_c71a69f05303c15c.png" name="Picture 6" align="bottom" width="436" height="354" border="0"> | |
</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in"><br> | |
<br> | |
</p> | |
<h1 class="western" align="justify"><strong>SkyBox Behaviour</strong></h1> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in"><br> | |
<br> | |
</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in">You | |
can create a sky box using 6 pre-rendered images. It doesn’t matter | |
where you place this on the 2D editor, but it just needs to be on the | |
scene to take effect. And you need to add 6 animations with names | |
these names.</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in">px, | |
py, pz, nx, ny, nz</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in"><img src="BabylonGD_html_1e70cc927924d844.png" name="Picture 7" align="bottom" width="601" height="612" border="0"> | |
</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in">px | |
means positive-x and nx means negative x. And the others are similar.</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in">You | |
can use below image as reference:</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in"><img src="BabylonGD_html_787f979bd8a7532f.png" name="Image3" align="bottom" width="512" height="384" border="0"> | |
</p> | |
<h1 class="western" align="justify"><br> | |
</h1> | |
<h1 class="western" align="justify"><strong>SkyMaterial Behaviour</strong></h1> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in"><br> | |
<br> | |
</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in">You | |
can also create realistic and procedural sky without using | |
pre-rendered images. You can dynamically specify things like sun | |
position, turbidity, inclination, etc. | |
</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in">This | |
behaviour could be attached to any sprite or any object. It doesn’t | |
matter where it’s located, and it doesn't matter what image you | |
use. But you can add a dummy image so you can locate in on the scene | |
editor.</p> | |
<h1 class="western" align="justify"><strong>Simple Sprite Behaviour</strong></h1> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in"><br> | |
<br> | |
</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in">You | |
can use 2D sprites on 3D space. The sprite will always be looking at | |
the camera. This is a very useful for technique for non-realistic | |
games where you don’t need to create lots of 3D models with time | |
consuming animations. | |
</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in">The | |
most important thing is that your sprite should have an animation | |
called DEFAULT. It’s only needed for some initial settings. You can | |
switch to other animations using the usual GDevelop events. | |
Babylon.js will render the active GDevelop animation.</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in"><br> | |
<br> | |
</p> | |
<h1 class="western" align="justify"><br> | |
</h1> | |
<h1 class="western" align="justify"><strong>Light Behaviour</strong></h1> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in"><br> | |
<br> | |
</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in">Light | |
is needed for camera to show 3D objects. Otherwise, everything will | |
be dark. Currently only Hemispheric Light is supported. Other light | |
sources will be added for future releases.</p> | |
<h1 class="western" align="justify"><strong>Terrain Behaviour</strong></h1> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in"><br> | |
<br> | |
</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in">You | |
can create a terrain from a height map and include mix maps. To use a | |
terrain, you need to create a sprite with 8 animations (only first | |
images of the animations will be used).</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in"><img src="BabylonGD_html_a1147fb3e724a8c9.png" name="Image4" align="bottom" width="602" height="613" border="0"> | |
</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in"><br> | |
<br> | |
</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in"><strong>HEIGHTMAP</strong>: | |
The actual heightmap for the terrain. Black parts are the ground, and | |
the white parts are the mountains.</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in"><strong>MIXMAP</strong>: | |
This will define how the textures will be mapped to RGB values. | |
</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in"><strong>GROUND</strong>: | |
Ground texture in the mixmap.</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in"><strong>MIDDLE</strong>: | |
Middle texture in the mixmap</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in"><strong>HIGH</strong>: | |
High texture in the mixmap.</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in"><strong>GROUND_N</strong>: | |
Ground normal texture in the mixmap.</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in"><strong>MIDDLE_N</strong>: | |
Middle normal texture in the mixmap</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in"><strong>HIGH_N</strong>: | |
High normal texture in the mixmap.</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in"><br> | |
<br> | |
</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in">You | |
also need to specify behaviour properties.</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in"><strong>Max | |
Height</strong>: Defines how high the tallest point of the terrain will | |
be. 100px=1unit in Babylon</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in"><strong>Min | |
Height</strong>: Defines how shallow the deepest point of the terrain will | |
be. 100px=1unit in Babylon</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in"><strong>Subdivisions</strong>: | |
This defines the quality of the terrain. If you or your audience have | |
low graphics, try setting this to a lower value. Around 150 is a good | |
number for average machines but try 50 or lower for low-spec | |
machines.</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in"><br> | |
<br> | |
</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in">If | |
you stretch or rotate the terrain sprite, 3D object will also be | |
rotated and stretched making it “what you see is what you get” in | |
2D editor.</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in"><br> | |
<br> | |
</p> | |
<p align="justify" style="line-height: 108%; margin-bottom: 0.11in"><br> | |
<br> | |
</p> |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment