diff --git a/website/src/app/documentation/advanced/compressing-textures/page.tsx b/website/src/app/documentation/advanced/compressing-textures/page.tsx index d1c2a6e87..15e53cc75 100644 --- a/website/src/app/documentation/advanced/compressing-textures/page.tsx +++ b/website/src/app/documentation/advanced/compressing-textures/page.tsx @@ -1,128 +1,108 @@ "use client"; -import { Fade } from "react-awesome-reveal"; -import { IoIosWarning } from "react-icons/io"; - -import { CodeBlock } from "../../code"; -import { CustomLink } from "../../link"; +import { Callout, CodeBlock, CustomLink, DocPage, DocHeading } from "../../components"; import { cliPack, enableKtx2 } from "./scripts"; export default function DocumentationCompressingTexturesPage() { return ( -
-
- - -
Compressing textures
- - - - -
-
Introduction
- -
- Compressed textures are used to reduce the size in video memory without sacrificing quality. Compressing textures can be done automatically when - exporting the project but can require time to compute depending on the number of textures and their size. -
- -
- Compressed textures are not necessary less heavy in terms of file size but are optimized for GPU usage. Therefore, they can significantly reduce the{" "} - memory usage and also increase the performance of your game in terms of rendering speed by reducing the internal bandwidth transfers. -
- -
- To compress textures using Babylon.js Editor, 2 methods are available: -
    -
  • - PVRTexTool: A command-line tool provided by{" "} - Imagination Technologies used to generate one{" "} - .ktx texture file per format (ASCT, DXT, ETC1, ETC2 and PVRTC). -
    • -
  • - KTX-Software: An open-source texture compression CLI provided by the{" "} - Khronos Group that supports KTX 2.0 container. Compared to PVRTexTool which - generates one KTX file per format, KTX-Software is capable of creating a unique KTX 2.0 file per texture that is supported on all platforms - which makes the compression process much faster and less storage consuming. -
    • -
-
- -
Installing KTX-Software
- -
- KTX-Software can be downloaded from their release page on Github. - Only versions 4.x are supported. Download the appropriate package according to your current operating system (Windows, Linux or MacOS) and install it on - your machine. -
- -
- -
- The KTX-Software installer may ask to install the command in PATH. This option must be enabled so the Babylon.js Editor can use the command. -
-
- -
Once installed, a new command is available on your system. To verify and try it, open a terminal and type the following command:
- - - -
Enabling KTX-Software in your project
- -
- Compressing textures in the Babylon.js Editor can be enabled by opening the project's configuration. To acess the project's settings, simply use the - main toolbar Edit {"->"} Project. In the Editor tab of the project's settings and under the "Textures" section, 3 options are - available for compressing textures: -
- -
Enabled
- -
- Sets wether or not compressing textures is enabled when exporting the project. By default, this option is not enabled. When using Babylon.js Editor CLI, - this option will also be used to determine if textures should be compressed during the generation process. -
- -
Enabled in preview
- -
- Sets wether or not textures used in the editor are also compressed. By default, this option is disabled. Using KTX allows to load textures faster. - Enabling this feature will make the used textures in each scene being compressed and stored in the temporary directory .bjseditor available in - the root folder of the project and scenes will load way faster than using original .png, .jpg, etc. textures. -
- -
- Compressing temporary textures for the editor is done on the fly and will not affect the original texture files. To not overload the editor's process on - your computer, textures are compressed one by one (not parallelized) and quality is set to Very fast. -
- -
Quality
- -
- The quality of the compression can be set to either Very fast, Fast, Normal or High. The higher the quality, the longer the - compression process will take but the better the result will be. By default, the quality is set to Very fast. -
- -
Using Babylon.js Editor CLI
- -
- When packing the assets of your project using the Babylon.js Editor CLI, textures will be automatically compressed if the option is enabled in the - project configuration. If not, only the original textures (.png, .jpg, etc.) will be packed without compression. -
- - - -
Enabling KTX2 in your game
- -
- In your project, scenes are being loaded using the loadScene method from the babylonjs-editor-tools package. It is important to notify the - package that KTX2 compressed textures should be used when loading the scene. To do so, simply call the following method before loading the scene: -
- - -
- + + Introduction + +

+ Compressed textures are used to reduce the size in video memory without sacrificing quality. Compressing textures can be done automatically when exporting the + project but can require time to compute depending on the number of textures and their size. +

+ +

+ Compressed textures are not necessarily less heavy in terms of file size but are optimized for GPU usage. Therefore, they can significantly reduce the{" "} + memory usage and also increase the performance of your game in terms of rendering speed by reducing the internal bandwidth transfers. +

+ +
+

To compress textures using Babylon.js Editor, 2 methods are available:

+ +
    +
  • + PVRTexTool: a command-line tool provided by{" "} + Imagination Technologies used to generate one .ktx{" "} + texture file per format (ASCT, DXT, ETC1, ETC2 and PVRTC). +
    • +
  • + KTX-Software: an open-source texture compression CLI provided by the Khronos Group that + supports the KTX 2.0 container. Compared to PVRTexTool which generates one KTX file per format, KTX-Software is capable of creating a unique KTX 2.0 + file per texture that is supported on all platforms which makes the compression process much faster and less storage consuming. +
    • +
-
+ + Installing KTX-Software + +

+ KTX-Software can be downloaded from their release page on GitHub. Only + versions 4.x are supported. Download the appropriate package according to your current operating system (Windows, Linux or MacOS) and install it on your machine. +

+ + + The KTX-Software installer may ask to install the command in PATH. This option must be enabled so the Babylon.js Editor can use the command. + + +

Once installed, a new command is available on your system. To verify and try it, open a terminal and type the following command:

+ + + + Enabling KTX-Software in your project + +

+ Compressing textures in the Babylon.js Editor can be enabled by opening the project's configuration. To access the project's settings, simply use the main toolbar{" "} + Edit {"->"} Project. In the Editor tab of the project's settings and under the Textures section, 3 options are available for compressing + textures: +

+ + Enabled + +

+ Sets whether or not compressing textures is enabled when exporting the project. By default, this option is not enabled. When using Babylon.js Editor CLI, this + option will also be used to determine if textures should be compressed during the generation process. +

+ + Enabled in preview + +

+ Sets whether or not textures used in the editor are also compressed. By default, this option is disabled. Using KTX allows to load textures faster. Enabling this + feature will make the used textures in each scene being compressed and stored in the temporary directory .bjseditor available in the root folder of the + project and scenes will load way faster than using original .png, .jpg, etc. textures. +

+ +

+ Compressing temporary textures for the editor is done on the fly and will not affect the original texture files. To not overload the editor's process on your + computer, textures are compressed one by one (not parallelized) and quality is set to Very fast. +

+ + Quality + +

+ The quality of the compression can be set to either Very fast, Fast, Normal or High. The higher the quality, the longer the compression + process will take but the better the result will be. By default, the quality is set to Very fast. +

+ + Using Babylon.js Editor CLI + +

+ When packing the assets of your project using the Babylon.js Editor CLI, textures will be automatically compressed if the option is enabled in the project + configuration. If not, only the original textures (.png, .jpg, etc.) will be packed without compression. +

+ + + + Enabling KTX2 in your game + +

+ In your project, scenes are being loaded using the loadScene method from the babylonjs-editor-tools package. It is important to notify the package + that KTX2 compressed textures should be used when loading the scene. To do so, simply call the following method before loading the scene: +

+ + + ); } diff --git a/website/src/app/documentation/advanced/lod-collisions/page.tsx b/website/src/app/documentation/advanced/lod-collisions/page.tsx index 4733673f1..567373fb6 100644 --- a/website/src/app/documentation/advanced/lod-collisions/page.tsx +++ b/website/src/app/documentation/advanced/lod-collisions/page.tsx @@ -1,23 +1,13 @@ "use client"; -import { Fade } from "react-awesome-reveal"; +import { Callout, DocPage } from "../../components"; export default function DocumentationLODCollisionsPage() { return ( -
-
- - -
LOD collisions
- - - - -
-
Coming soon
-
- -
-
+ + + The content of this page is on its way. Stay tuned! + + ); } diff --git a/website/src/app/documentation/advanced/optimizing-shadows/page.tsx b/website/src/app/documentation/advanced/optimizing-shadows/page.tsx index 5cb64f5fa..0770a4d86 100644 --- a/website/src/app/documentation/advanced/optimizing-shadows/page.tsx +++ b/website/src/app/documentation/advanced/optimizing-shadows/page.tsx @@ -1,27 +1,13 @@ "use client"; -import { Fade } from "react-awesome-reveal"; - -// import { NextChapterComponent } from "../../components/next-chapter"; +import { Callout, DocPage } from "../../components"; export default function DocumentationOptimizingShadowsPage() { return ( -
-
- - -
Optimizing shadows
- - - - -
-
Coming soon
- - {/* */} -
- -
-
+ + + The content of this page is on its way. Stay tuned! + + ); } diff --git a/website/src/app/documentation/assets/using-sprite-manager/page.tsx b/website/src/app/documentation/assets/using-sprite-manager/page.tsx index 66b5e2577..d86f18058 100644 --- a/website/src/app/documentation/assets/using-sprite-manager/page.tsx +++ b/website/src/app/documentation/assets/using-sprite-manager/page.tsx @@ -1,160 +1,117 @@ "use client"; -import Link from "next/link"; - -import { Fade } from "react-awesome-reveal"; - -import { CodeBlock } from "../../code"; +import { CodeBlock, CustomLink, DocPage, DocHeading, DocVideo } from "../../components"; import { assignScriptSprite, assignScriptSpriteManager, getAnimationSprite, playAnimationSprite } from "./scripts"; -export default function DocumentationRunningProjectPage() { +export default function DocumentationUsingSpriteManagerPage() { return ( -
-
- - -
Using Sprite Manager
- - - - -
-
Introduction
- -
- The editor provides support for using Sprite managers in your scenes. Sprite managers allow to efficiently render a large number of sprites in the scene - using a single texture. More information about sprite managers{" "} - - here - -
- -
- To create a new sprite manager, just right-click somewhere in the graph and select Sprite Manager. The sprite manager will be created with - default parameters and no asset assigned to it. -
- -
- Once created, the sprite manager can be configured using the inspector by selecting it in the graph. A sprite manager can use either a single texture or - a pair of JSON atlas with a texture. -
- -
- -
- -
Configuring with single texture
- -
- When using a single texture for the sprite manager, simply drag'n'drop the desired image asset in the Texture property of the inspector. The - image will be used as the texture for all sprites created with this manager. Once the texture is assigned, you'll be able to create sprites using this - manager. -
- -
- -
- -
- By default, the sprite dimensions are set to 64x64. This can be customized by setting the Cell Width and Cell Height properties in - the inspector to the desired values. When dimensions changed the grid of all instantiable sprites will be updated accordingly. -
- -
- To add a new sprite in the scene, simply drag'n'drop the desired sprite from the grid to the scene. The sprite will be created at the dropped position. -
- -
- -
- -
Configuring with Atlas JSON
- -
- When using an atlas JSON file, both the JSON file and the associated texture must be assigned to the sprite manager. To do so, select the Packed{" "} - mode and simply drag'n'drop the JSON file in the Atlas JSON property of the inspector. The editor will automatically search for the associated - texture in the assets and assign it to the - Texture property. -
- -
- Compared to using a single texture, using an atlas JSON allows to have sprites of varying sizes and not constrained to a fixed grid. In other words, no - need to configure Cell Width and Cell Height. Once the atlas JSON is assigned, you'll be able to create sprites by drag'n'dropping them - from the grid to the scene. -
- -
- -
- -
Assigning script to a Sprite
- -
- Scripts can be assigned to individual sprites created from a sprite manager. When assigning a script to a sprite, the sprite instance can be accessed in - the script using the Sprite type from the @babylonjs/core package: -
- - - -
Adding animations
- -
Sprite managers support animations. Animations can be created per sprite.
- -
- To add a new animation, click the "+" button. A new animation will be created with default parameters. You can then customize the animation by - setting the Name, From, To and Delay properties in the inspector. To play the selected animation just click the "Play - " button or "Stop" button to stop it. -
- -
- To remove an animation, select it in the list and click the "-" button. -
- -
- -
- -
- To play an animation from a script, you can use the playSpriteAnimationFromName function from the babylonjs-editor-tools package. This - function allows to play an animation by its name: -
- - - -
- Alternatively, you can use the animationFromSprite decorator from the babylonjs-editor-tools package to easily retrieve an animation by - its name and play it: -
- - - -
Assigning script to Sprite Manager
- -
- Sprite managers are represented as nodes in the editor. A special type exists for them in the babylonjs-editor-tools package:{" "} - SpriteManagerNode. When assigning a script to a Sprite Manager node, the node instance can be accessed in the script using the{" "} - SpriteManagerNode type. -
- -
- To access the SpriteManager instance of Babylon.js, use the .spriteManager property of the node: -
- - -
- -
-
+ + Introduction + +

+ The editor provides support for using Sprite managers in your scenes. Sprite managers allow to efficiently render a large number of sprites in the scene using a + single texture. More information about sprite managers{" "} + here. +

+ +

+ To create a new sprite manager, just right-click somewhere in the graph and select Sprite Manager. The sprite manager will be created with default parameters + and no asset assigned to it. +

+ +

+ Once created, the sprite manager can be configured using the inspector by selecting it in the graph. A sprite manager can use either a single texture or a pair of + JSON atlas with a texture. +

+ + + + Configuring with single texture + +

+ When using a single texture for the sprite manager, simply drag'n'drop the desired image asset in the Texture property of the inspector. The image will be + used as the texture for all sprites created with this manager. Once the texture is assigned, you'll be able to create sprites using this manager. +

+ + + +

+ By default, the sprite dimensions are set to 64x64. This can be customized by setting the Cell Width and Cell Height properties in the + inspector to the desired values. When dimensions changed the grid of all instantiable sprites will be updated accordingly. +

+ +

To add a new sprite in the scene, simply drag'n'drop the desired sprite from the grid to the scene. The sprite will be created at the dropped position.

+ + + + Configuring with Atlas JSON + +

+ When using an atlas JSON file, both the JSON file and the associated texture must be assigned to the sprite manager. To do so, select the Packed mode and + simply drag'n'drop the JSON file in the Atlas JSON property of the inspector. The editor will automatically search for the associated texture in the assets + and assign it to the Texture property. +

+ +

+ Compared to using a single texture, using an atlas JSON allows to have sprites of varying sizes and not constrained to a fixed grid. In other words, no need to + configure Cell Width and Cell Height. Once the atlas JSON is assigned, you'll be able to create sprites by drag'n'dropping them from the grid to the + scene. +

+ + + + Assigning script to a Sprite + +

+ Scripts can be assigned to individual sprites created from a sprite manager. When assigning a script to a sprite, the sprite instance can be accessed in the script + using the Sprite type from the @babylonjs/core package: +

+ + + + Adding animations + +

Sprite managers support animations. Animations can be created per sprite.

+ +

+ To add a new animation, click the + button. A new animation will be created with default parameters. You can then customize the animation by setting the{" "} + Name, From, To and Delay properties in the inspector. To play the selected animation just click the Play button or the{" "} + Stop button to stop it. +

+ +

+ To remove an animation, select it in the list and click the - button. +

+ + + +

+ To play an animation from a script, you can use the playSpriteAnimationFromName function from the babylonjs-editor-tools package. This function allows + to play an animation by its name: +

+ + + +

+ Alternatively, you can use the animationFromSprite decorator from the babylonjs-editor-tools package to easily retrieve an animation by its name and + play it: +

+ + + + Assigning script to Sprite Manager + +

+ Sprite managers are represented as nodes in the editor. A special type exists for them in the babylonjs-editor-tools package: SpriteManagerNode. When + assigning a script to a Sprite Manager node, the node instance can be accessed in the script using the SpriteManagerNode type. +

+ +

+ To access the SpriteManager instance of Babylon.js, use the .spriteManager property of the node: +

+ + + ); } diff --git a/website/src/app/documentation/basics/adding-scripts/page.tsx b/website/src/app/documentation/basics/adding-scripts/page.tsx index b3f384067..29800cab8 100644 --- a/website/src/app/documentation/basics/adding-scripts/page.tsx +++ b/website/src/app/documentation/basics/adding-scripts/page.tsx @@ -1,155 +1,124 @@ "use client"; -import { Fade } from "react-awesome-reveal"; - -import { IoIosWarning } from "react-icons/io"; - -import { CodeBlock } from "../../code"; +import { Callout, CodeBlock, DocPage, DocHeading, DocVideo } from "../../components"; import { tsClassDecoratorsExample } from "./from-scene"; import { tsClassBasedExample, tsFunctionBasedExample } from "./examples"; export default function DocumentationAddingScriptsPage() { return ( -
-
- - -
Adding scripts
- - - - -
-
Introduction
- -
- The editor allows to add scripts to your project in order to add interactivity to your scenes. The scripts are written in TypeScript and consist on 2 - main methods: -
- -
    -
  • - onStart: Called when the script is loaded and the scene is ready. -
    • -
  • - onUpdate: Called each time a frame is rendered on the screen. -
    • -
- -
- Scripts are made to be attached to objects and multiple scripts can be attached to the same object. Linked with the babylonjs-editor-tools{" "} - package installed with the project, some useful decorators are available to help retrieving objects and customizing the scripts. -
- -
- - -
- This feature is still Work in progress and some features like decorators are not yet available for function-based scripts. -
-
- -
- Scripts can be written using both methods class-based: -
- - - -
- and function-based: -
- - - -
Adding script
- -
- The first steps consists on creating a new script before it can be applied on an object. -
- To do so, right-click somewhere in the src folder of the project using the Assets Browser panel in the editor and select{" "} - - Add {"->"} Script {"->"} Class based - {" "} - or{" "} - - Add {"->"} Script {"->"} Function based - -
- -
- -
- -
Attaching script
- -
- Once a script is available in the sources folder, just select an object in the scene (a mesh for example) so the inspector shows the properties of the - mesh and then drag'n'drop the script file from the Assets Browser panel to the Scripts section in the inspector. -
- -
Once done, the script is attached to be object and will be executed automatically when running the application.
- -
- -
- -
Using decorators to retrieve objects
- -
- The babylonjs-editor-tools package provides some useful decorators to help retrieving objects and customizing the scripts. -
- -
Available decorators are:
- -
    -
  • - @nodeFromScene: Retrieve the reference of the first node that has the given name by traversing the entire scene graph. -
    • -
  • - @nodeFromDescendants: Retrieve the reference of the first node that has the given name but only if the node is a descendant of the object the - script is attached to. -
    • -
  • - @particleSystemFromScene: Retrieve the reference of the first particle system that has the given name by traversing the entire scene graph. -
    • -
  • - @soundFromScene: Retrieve the reference of the first sound that has the given name. -
    • -
- -
- Those decorators are equivalent to calling the associated methods like scene.getMeshById("..."), scene.getTransformNodeById("...") etc.. -
- -
- - -
- Those decorators can be used only by scripts using Classes and are processed when the script is loaded. So the decorated properties are not - available in the constructor method. -
-
- -
- - -
- Those decorators are available in the babylonjs-editor-tools package that is provided as a depdendency in the package.json file. In - case a decorator that is documented here is not available in the code, make sure to install the up-to-date package in your project. -
-
- -
Example:
- - -
- + + Introduction + +
+

+ The editor allows to add scripts to your project in order to add interactivity to your scenes. The scripts are written in TypeScript and consist on 2 main + methods: +

+ +
    +
  • + onStart: called when the script is loaded and the scene is ready. +
    • +
  • + onUpdate: called each time a frame is rendered on the screen. +
    • +
-
+ +

+ Scripts are made to be attached to objects and multiple scripts can be attached to the same object. Linked with the babylonjs-editor-tools package installed + with the project, some useful decorators are available to help retrieving objects and customizing the scripts. +

+ + + This feature is still a work in progress and some features like decorators are not yet available for function-based scripts. + + +

+ Scripts can be written using both methods, class-based: +

+ + + +

+ and function-based: +

+ + + + Adding script + +

+ The first steps consists on creating a new script before it can be applied on an object. +
+ To do so, right-click somewhere in the src folder of the project using the Assets Browser panel in the editor and select{" "} + + Add {"->"} Script {"->"} Class based + {" "} + or{" "} + + Add {"->"} Script {"->"} Function based + + . +

+ + + + Attaching script + +

+ Once a script is available in the sources folder, just select an object in the scene (a mesh for example) so the inspector shows the properties of the mesh and then + drag'n'drop the script file from the Assets Browser panel to the Scripts section in the inspector. +

+ +

Once done, the script is attached to the object and will be executed automatically when running the application.

+ + + + Using decorators to retrieve objects + +

+ The babylonjs-editor-tools package provides some useful decorators to help retrieving objects and customizing the scripts. +

+ +
+

Available decorators are:

+ +
    +
  • + @nodeFromScene: retrieve the reference of the first node that has the given name by traversing the entire scene graph. +
    • +
  • + @nodeFromDescendants: retrieve the reference of the first node that has the given name but only if the node is a descendant of the object the script + is attached to. +
    • +
  • + @particleSystemFromScene: retrieve the reference of the first particle system that has the given name by traversing the entire scene graph. +
    • +
  • + @soundFromScene: retrieve the reference of the first sound that has the given name. +
    • +
+
+ +

+ Those decorators are equivalent to calling the associated methods like scene.getMeshById("..."), scene.getTransformNodeById("...") etc. +

+ + + Those decorators can be used only by scripts using classes and are processed when the script is loaded. So the decorated properties are not available in the{" "} + constructor method. + + + + Those decorators are available in the babylonjs-editor-tools package that is provided as a dependency in the package.json file. In case a decorator + that is documented here is not available in the code, make sure to install the up-to-date package in your project. + + +

Example:

+ + + ); } diff --git a/website/src/app/documentation/basics/composing-scene/page.tsx b/website/src/app/documentation/basics/composing-scene/page.tsx index d44b6dc2d..2516d74a6 100644 --- a/website/src/app/documentation/basics/composing-scene/page.tsx +++ b/website/src/app/documentation/basics/composing-scene/page.tsx @@ -1,212 +1,160 @@ "use client"; -import { Fade } from "react-awesome-reveal"; - -import { CustomLink } from "../../link"; +import { DocPage, DocHeading, DocVideo, DocImage, Callout, CustomLink } from "../../components"; export default function DocumentationComposingScenePage() { return ( -
-
- - -
Composing scene
- - - - -
-
Introduction
- -
The layout of the editor is divided into 4 main parts:
- -
    -
  • - Graph: by default on the left side, shows the structure of the scene that is being edited. -
    • -
  • - Preview: by default in center, where you can see and interact with the scene. -
    • -
  • - Inspector: by default on the right side, where you can see and edit the properties of the selected object. -
    • -
  • - Assets Browser: by default on the bottom side, where you can see and manage the assets of the project (textures, materials, meshes, etc.). -
    • -
- -
- Each time a node is clicked in the graph or in the preview, the inspector is updated to show the properties of the selected object. -
- The layout of the inspector may change according to the nature of the edited object. -
- -
- -
- -
Using gizmos
- -
- In order to move, rotate and scale selected object, gizmos may be used. -
- For a complete understanding of gizmos, you can refer to this{" "} - - Babylon.js documentation - -
- -
In the editor, gizmos are available in the preview's panel toolbar or via shortcut:
- -
    -
  • - CTRL+T or ⌘+T for Position gizmos -
    • -
  • - CTRL+R or ⌘+R for Rotation gizmos -
    • -
  • - CTRL+D or ⌘+D for Scaling gizmos -
    • -
- -
- -
- -
Adding objects
- -
- The editor supports adding primitive objects such as meshes, lights and cameras. -
- By default, the template already contains an{" "} - - Universal camera - - , a{" "} - - Point light - - , a{" "} - - Box - {" "} - and a{" "} - - Ground - - . -
- -
- You can add more objects by clicking on the Add button in the main toolbar of the editor. Each time a new object is added, it is placed at the - center of the scene and the graph is updated in order to show the newly added node. -
- -
- -
- -
- Each object can be customized. Those meshes (box, sphere, ground, etc.) are called "primitives" and their geometry is generated automatically by - Babylon.js. Those geometries are created using default values and you can edit them in the inspector. -
- -
Adding custom 3d models
- -
- The editor supports multiple file formats for 3D models such as .glb, .gltf, .obj, .fbx, .babylon, .stl and{" "} - .blend. -
- -
- Note: each time a .fbx is imported, the editor will send the file to our server in order to be - converted automatically. -
- The server is located at editor.babylonjs.com and you can find the sources of the - converter here on Github. -
- -
- To do so, let's add our first 3d model in the assets of the project. Using the Assets Browser, click "Import". A file dialog appears, - select all the files of the 3d model (3d file and textures) and click "Open". -
- -
- -
- -
- In order to keep the assets organized, you can create folders in the assets browser by right-clicking on the panel and by selecting the " - New Folder" option. To rename a folder or a file, just double-click on its name. -
- Once the folder is created, just double-click on it and import your assets in it. -
- -
- -
- -
- Here, for this example, we imported a .gltf file with all its associated textures. In oder to import the 3d model, simply drag'n'drop the{" "} - .gltf file on the preview. -
- Once loaded, the editor will place all the root nodes of the 3d model according to where the file was dropped in the preview. -
- -
- Sometimes, models are exported with scales that differ from your projects. In order to fix this, simply select the root nodes and re-scale them using - the inspector. -
- Note: Here we imported a .gltf file. The GLTF loader of Babylon.js always creates a __root__ node that we can use to re-scale the - entire 3d model. -
-
- -
- -
- -
When you add a 3d model, all its materials and textures are automatically applied on it (most of the time).
- -
Managing hidden files
- -
-
-
- In cases the loaded 3d model contains embedded textures, typically all .glb and some .fbx files, the editor will - automatically extract them and place them in the assets browser in the same folder. -
- -
- In order to keep files organized, those generated texture files are hidden by default in the assets browser. You can show them by clicking on - the Filters button on the right side and check "Show Generated Files". -
- -
- To make a file not hidden for the assets browser, just rename the file by removing the prefix "editor-generated_". Most of the time, - you'll not need to touch those files. -
- But in case you have to modify those textures without modifying the original 3d model, you can iterate by replacing the texture directly in the - assets browser. -
-
- - -
-
- -
-
+ + Introduction + +

The layout of the editor is divided into 4 main parts:

+ +
    +
  • + Graph: by default on the left side, shows the structure of the scene that is being edited. +
    • +
  • + Preview: by default in center, where you can see and interact with the scene. +
    • +
  • + Inspector: by default on the right side, where you can see and edit the properties of the selected object. +
    • +
  • + Assets Browser: by default on the bottom side, where you can see and manage the assets of the project (textures, materials, meshes, etc.). +
    • +
+ +

+ Each time a node is clicked in the graph or in the preview, the inspector is updated to show the properties of the selected object. +
+ The layout of the inspector may change according to the nature of the edited object. +

+ + + + Using gizmos + +

+ In order to move, rotate and scale selected objects, gizmos may be used. +
+ For a complete understanding of gizmos, you can refer to the{" "} + + Babylon.js documentation + + . +

+ +

In the editor, gizmos are available in the preview panel toolbar or via shortcut:

+ +
    +
  • + CTRL+T or{" "} + ⌘+T for Position gizmos +
    • +
  • + CTRL+R or{" "} + ⌘+R for Rotation gizmos +
    • +
  • + CTRL+D or{" "} + ⌘+D for Scaling gizmos +
    • +
+ + + + Adding objects + +

+ The editor supports adding primitive objects such as meshes, lights, and cameras. +
+ By default, the template already contains a{" "} + + Universal camera + + , a{" "} + + Point light + + , a{" "} + + Box + + , and a{" "} + + Ground + + . +

+ +

+ You can add more objects by clicking on the Add button in the main toolbar of the editor. Each time a new object is added, it is placed at the center of the + scene and the graph is updated to show the newly added node. +

+ + + +

+ Each object can be customized. Those meshes (box, sphere, ground, etc.) are called "primitives" and their geometry is generated automatically by Babylon.js. Those + geometries are created using default values and you can edit them in the inspector. +

+ + Adding custom 3D models + +

+ The editor supports multiple file formats for 3D models such as .glb, .gltf, .obj, .fbx, .babylon, .stl, and .blend + . +

+ + + Each time a .fbx file is imported, the editor will send the file to the conversion server to be converted automatically. The server is located at{" "} + editor.babylonjs.com and you can find the sources of the converter{" "} + here on GitHub. + + +

+ To add your first 3D model, click Import in the Assets Browser. When the file dialog appears, select all the files of the 3D model (3D file and + textures) and click Open. +

+ + + +

+ In order to keep the assets organized, you can create folders in the assets browser by right-clicking on the panel and selecting the New Folder option. To + rename a folder or a file, double-click on its name. +

+ + + +

+ In this example, we imported a .gltf file with all its associated textures. To place the 3D model into the scene, drag and drop the .gltf file onto + the preview. Once loaded, the editor places all the root nodes of the 3D model where the file was dropped. +

+ + + Sometimes, models are exported with scales that differ from your project. To fix this, select the root nodes and re-scale them using the inspector. For GLTF files, + the Babylon.js loader creates a __root__ node that you can use to re-scale the entire 3D model. + + + + + Managing hidden files + +

+ When a loaded 3D model contains embedded textures (typically all .glb and some .fbx files), the editor will automatically extract them and place them + in the assets browser in the same folder. +

+ +

+ To keep files organized, generated texture files are hidden by default in the assets browser. You can show them by clicking on the Filters button on the + right side and checking Show Generated Files. +

+ + + +

+ To make a file visible permanently in the assets browser, rename the file to remove the prefix editor-generated_. +

+ ); } diff --git a/website/src/app/documentation/basics/creating-project/page.tsx b/website/src/app/documentation/basics/creating-project/page.tsx index 8c2d5691b..c4c88688e 100644 --- a/website/src/app/documentation/basics/creating-project/page.tsx +++ b/website/src/app/documentation/basics/creating-project/page.tsx @@ -1,165 +1,104 @@ "use client"; -import { Fade } from "react-awesome-reveal"; +import { DocPage, DocHeading, DocImage, Callout } from "../../components"; export default function DocumentationCreatingProjectPage() { return ( -
-
- - -
Creating a project
- - - - -
-
Dashboard
- -
- When opening the Babylon.js Editor application, the first window that appears is the dashboard. -
- The dashboard is the place where you can create, open, and manage your projects. -
- By default, the dashboard is empty showing no project has been found. -
- - - -
- Two options here: -
    -
  • - Click the "Create project" button to create a new project. -
    • -
  • - Click the "Import project" in order to register and already existing project in the dashboard. -
    • -
-
- -
Create project
- - {/*
- - -
- A new project is created based on a template that runs with Next.JS. It is highly recommanded to have a basic understanding of{" "} - - - React - - {" "} - and{" "} - - - Next.JS - - {" "} - before starting. -
-
*/} - -
Selecting destination
- -
- When creating a new project, the dashboard asks for a folder where to locate the created project. Click the "Browse..." button and select an{" "} - empty folder. -
- -
Choosing package manager
- -
- The editor will do things automatically such as installing dependencies for the newly created project. You can select the desired package manager in the - dropdown list where each package manager is tested to ensure it is available on your system. It supports major package managers such as: -
    -
  • - npm: comes preinstalled with Node.js. Stable, reliable, and widely supported. -
    • -
  • - yarn: a popular alternative to npm, known for its speed and reliability. -
    • -
  • - pnpm: uses a clever content-addressable store to save space and speed up installs. Strict and deterministic. -
    • -
  • - bun: selecting bun means that the bun runtime is used instead of Node.js. -
    • -
-
- -
Choosing template
- -
- The editor provides 3 templates to start with: -
    -
  • - Next.js: a minimal template preconfigured to use Next.js. It includes a minimal setup with a single page and a simple scene. -
    • -
  • - SolidJS: a minimal template preconfigured to use SolidJS. It includes a minimal setup with a single page and a simple scene. -
    • -
  • - Vanilla: a basic template suitable for custom setups. -
    • -
  • - Electron: a minimal template preconfigured to use Electron. It includes a minimal setup with a single window and a simple scene. -
    • -
-
- - - -
- Once you are ready, just click the "Create" button and a new project will appear in the dashboard. -
- This project is now ready to be opened and edited. Because it has never been opened, a "question mark" icon is displayed. Each time a project is saved - in the editor, the icon will change to a preview image of the project. -
- - - -
Now, to open and edit the project, just double-click the project in the dashboard and the editor will open.
- - - -
- Each time a project is opened, the editor will update all dependencies by itself using the selected package manager. This step is mandatory and - cannot be skipped. -
- Dependencies are updated automatically to ensure the project is always up-to-date and working properly. -
- -
- Moreover, the editor supports plugins. Those plugins can be installed "per-project" so they are, by definition, dependencies of the project that - must be updated. -
- -
Import project
- -
-
-
- In case you already created a project and want to import it in your dashboard, you can use the "Import project" button. -
- The dashboard configuration is local to the computer. It means that if you have a project on another computer, you can import it in the - dashboard of the current computer. -
- -
- When importing a project, the dashboard asks for the project file. Just locate the right folder and select the ".bjseditor" file. -
- -
- Click "Open" and the project will be imported in the dashboard. -
-
- - -
-
- + + Dashboard + +

+ When opening the Babylon.js Editor application, the first window that appears is the dashboard. The dashboard is where you create, open, and manage your projects. + By default, the dashboard is empty until your first project is registered. +

+ + + +
+

From the dashboard, you have two options:

+
    +
  • + Click the Create project button to generate a new workspace. +
    • +
  • + Click Import project to register an already existing project on your machine. +
    • +
-
+ + Create project + + Selecting destination + +

+ When creating a new project, the dashboard asks for a target folder. Click Browse... and select an empty folder on your disk. +

+ + Choosing package manager + +

The editor automatically installs dependencies for the newly created project using your preferred package manager. You can select:

+ +
    +
  • + npm: Comes pre-installed with Node.js. Stable, reliable, and widely supported. +
    • +
  • + yarn: A popular alternative to npm known for speed and reliability. +
    • +
  • + pnpm: Uses a content-addressable store to save disk space and speed up installations. Strict and deterministic. +
    • +
  • + bun: Uses the fast Bun runtime and package manager. +
    • +
+ + Choosing template + +

The editor provides several preconfigured templates to get started quickly:

+ +
    +
  • + Next.js: Minimal template preconfigured to use Next.js with React. +
    • +
  • + SolidJS: Minimal template preconfigured with SolidJS. +
    • +
  • + Vanilla: Basic template suitable for custom web setups. +
    • +
  • + Electron: Minimal template preconfigured for desktop apps using Electron. +
    • +
+ + + +

+ Once configured, click Create and your new project will appear in the dashboard. +

+ + + + Opening and Editing + +

To open and edit your project, double-click on its card in the dashboard.

+ + + + + Each time a project is opened, the editor checks and updates dependencies using your selected package manager. This ensures all editor runtime tools and per-project + plugins are up-to-date and compatible. + + + Import project + +

+ If you already have a Babylon.js Editor project created previously or on another machine, click Import project. Locate your project folder, select the{" "} + .bjseditor file, and click Open. +

+ + + ); } diff --git a/website/src/app/documentation/basics/managing-assets/page.tsx b/website/src/app/documentation/basics/managing-assets/page.tsx index 1c9c507ec..ada6abfce 100644 --- a/website/src/app/documentation/basics/managing-assets/page.tsx +++ b/website/src/app/documentation/basics/managing-assets/page.tsx @@ -1,183 +1,133 @@ "use client"; -import { Fade } from "react-awesome-reveal"; - -import { IoIosWarning } from "react-icons/io"; - -import { CustomLink } from "../../link"; +import { Callout, CustomLink, DocPage, DocHeading, DocImage, DocVideo } from "../../components"; export default function DocumentationManagingAssetsPage() { return ( -
-
- - -
Managing assets
- - - - -
-
Introduction
- -
- This chapter is linked to the previous one (Composing scene) but goes deeper into the management of assets. How to create your own materials, how - to assign textures to materials, etc. -
- -
- - -
- It is important to note that all the assets used in your project must be located at least in the "/assets" folder in order to be correctly - understood by the editor. This "assets" folder is the root folder of all the assets used in your project and is also located in the root - folder of your project. -
-
- -
Creating your own materials
- -
- When importing a 3d model, most of the time it comes with its own materials and textures already configured. But sometimes you may want to have a deeper - control over the materials and see how its related assets (typically textures) appear using the Babylon.js engine. -
- -
Let's start with an empty box that we created using the primitive objects of the editor. By default the box has no material assigned to it.
- - - -
- To create a new material, go in the "assets" folder in the "Assets Browser" panel and right click in order to show the context menu and - select "Add". -
- -
- The editor supports both PBR and Standard materials. Most of the time, it is recommended to add PBR materials as it became the norm today. - For more information about PBR materials, you can refer to this{" "} - - excellent documentation - {" "} - of Babylon.js -
- -
- Once you clicked on "Add {"->"} PBR Material", a new asset file appears named "New PBR Material.material". Double-click on its name and - rename it to "my-material.material" or any other name you prefer. Always keeping a constant and logical naming of assets is important to keep - your assets organized. -
- -
- -
- -
- New created materials are empty by default. Now, to assign this material to the box or any other asset, you can drag and drop the material file on the - desired mesh in the "Preview" panel. -
- -
- - -
- Materials that are created manually are shared across all objects it's applied to. For example, if the material is assigned to 2 distinct meshes and - the material properties are edited, both meshes will be updated. -
-
- -
- -
- -
- Your own material is now applied on the box! Now the goal is to edit the material properties using the "Inspector" panel. To do so, just click on - the box in the "Preview" panel in order to edit the object. -
- Scroll a bit in the "Inspector" panel in order to see the "Material" section. Starting from here you can edit the material properties. -
- -
Assigning textures to materials
- -
- Because newly created materials are empty, you may want to assign textures to them. As for 3d models, textures are assets that can be imported in the " - assets" folder in the "Assets Browser" panel. -
- Let's create a "pbr" folder in the "assets" folder using the "Assets Browser" panel and import textures in it. -
- -
- -
- -
Here, 3 textures were imported:
- -
    -
  • - Albedo texture: the base color of the object. -
    • -
  • - Normal texture: to simulate bump and dents on the object's surface. More information about bump mapping{" "} - - here - -
    • -
  • - Metallic texture: texture containing both the metallic value in the B channel and the roughness value in the G channel to keep better - precision. Ambient occlusion can also be saved in R channel. -
    • -
- -
- To master the meaning of those textures, refer to the{" "} - - Babylon.js documentation - - . -
- -
- In the "Inspector" panel, all the available slots for textures are shown in the "Material Textures" section. To assign a texture, just - drag'n'drop the texture file from the "Assets Browser" panel to the slot in the inspector. -
- -
Once a texture is assigned, the slot is updated to show the preview of the texture and its potential properties to edit.
- -
- -
- -
- As an advanced user, you may want to edit the properties of a texture in a material, just click on the preview of the texture in the "Inspector" - panel. -
A new panel appears showing all the properties of the texture. Here you can edit the properties of the texture to fit your needs. -
- -
- -
- -
- Tip: you can also drag'n'drop a texture file directly on a mesh in the "Preview" panel. The editor will ask for the slot where to assign the - texture. -
- -
- -
-
- + + Introduction + +

+ This chapter is linked to the previous one (Composing scene) but goes deeper into the management of assets. How to create your own materials, how to assign + textures to materials, etc. +

+ + + All the assets used in your project must be located at least in the /assets folder in order to be correctly understood by the editor. This assets{" "} + folder is the root folder of all the assets used in your project and is also located in the root folder of your project. + + + Creating your own materials + +

+ When importing a 3D model, most of the time it comes with its own materials and textures already configured. But sometimes you may want to have a deeper control + over the materials and see how its related assets (typically textures) appear using the Babylon.js engine. +

+ +

Let's start with an empty box that we created using the primitive objects of the editor. By default the box has no material assigned to it.

+ + + +

+ To create a new material, go in the assets folder in the Assets Browser panel and right click in order to show the context menu and select Add. +

+ +

+ The editor supports both PBR and Standard materials. Most of the time, it is recommended to add PBR materials as it became the norm today. For more + information about PBR materials, you can refer to this{" "} + + excellent documentation + {" "} + of Babylon.js. +

+ +

+ Once you clicked on Add {"->"} PBR Material, a new asset file appears named New PBR Material.material. Double-click on its name and rename it to{" "} + my-material.material or any other name you prefer. Always keeping a constant and logical naming of assets is important to keep your assets organized. +

+ + + +

+ New created materials are empty by default. Now, to assign this material to the box or any other asset, you can drag and drop the material file on the desired mesh + in the Preview panel. +

+ + + Materials that are created manually are shared across all objects it is applied to. For example, if the material is assigned to 2 distinct meshes and the material + properties are edited, both meshes will be updated. + + + + +

+ Your own material is now applied on the box! Now the goal is to edit the material properties using the Inspector panel. To do so, just click on the box in + the Preview panel in order to edit the object. +
+ Scroll a bit in the Inspector panel in order to see the Material section. Starting from here you can edit the material properties. +

+ + Assigning textures to materials + +

+ Because newly created materials are empty, you may want to assign textures to them. As for 3D models, textures are assets that can be imported in the assets{" "} + folder in the Assets Browser panel. +
+ Let's create a pbr folder in the assets folder using the Assets Browser panel and import textures in it. +

+ + + +
+

Here, 3 textures were imported:

+ +
    +
  • + Albedo texture: the base color of the object. +
    • +
  • + Normal texture: to simulate bump and dents on the object's surface. More information about bump mapping{" "} + + here + + . +
    • +
  • + Metallic texture: texture containing both the metallic value in the B channel and the roughness value in the G channel to keep better precision. + Ambient occlusion can also be saved in R channel. +
    • +
-
+ +

+ To master the meaning of those textures, refer to the{" "} + + Babylon.js documentation + + . +

+ +

+ In the Inspector panel, all the available slots for textures are shown in the Material Textures section. To assign a texture, just drag'n'drop the + texture file from the Assets Browser panel to the slot in the inspector. +

+ +

Once a texture is assigned, the slot is updated to show the preview of the texture and its potential properties to edit.

+ + + +

+ As an advanced user, you may want to edit the properties of a texture in a material, just click on the preview of the texture in the Inspector panel. +
A new panel appears showing all the properties of the texture. Here you can edit the properties of the texture to fit your needs. +

+ + + + + You can also drag'n'drop a texture file directly on a mesh in the Preview panel. The editor will ask for the slot where to assign the texture. + + + + ); } diff --git a/website/src/app/documentation/basics/running-project/page.tsx b/website/src/app/documentation/basics/running-project/page.tsx index b65c98e8f..e2b2fa282 100644 --- a/website/src/app/documentation/basics/running-project/page.tsx +++ b/website/src/app/documentation/basics/running-project/page.tsx @@ -1,95 +1,58 @@ "use client"; -import { Fade } from "react-awesome-reveal"; -import { IoIosWarning } from "react-icons/io"; import { IoPlay, IoRefresh, IoStop } from "react-icons/io5"; +import { DocPage, DocHeading, DocVideo } from "../../components"; + export default function DocumentationRunningProjectPage() { return ( -
-
- - -
Running project
- - - - -
-
Introduction
- -
- Projects can be played directly from the editor. A project can be composed of multiple scenes and some scripts may be attached to objects in the - scene(s). -
- Here are 2 options: -
    -
  • - play the current scene: all the scripts are compiled on the fly and executed in the current scene that is displayed in the editor, - sharing the same resources (textures, etc.). This is the default behavior of the editor. -
    • -
  • - play the project as-is: consists on running the command dev using the project's selected package manager (npm, yarn, bun or pnpm). -
    • -
-
- - {/*
- - -
- Only the current scene being edited in the editor will be executed and all the scripts that are attached to the objects will be executed. -
-
*/} - -
Playing the current scene
- -
- To start the current scene, just click the start button -
- -
- located in the toolbar of the editor's preview panel. -
- -
- Each time the current scene is played, the editor will update the assets located in the public folder of the project. If new assets were added to - the project (especially images), this can take few seconds too to generate all new necessary files before the project can be played. -
- -
- Note that when playing, all the scripts are watched for changes and will be reloaded automatically when modified until the "play" mode is stopped. -
- -
Stopping the current scene
- -
- To stop the current scene being played and get back to the edit mode, just click the stop button -
- -
- located in the toolbar of the editor's preview panel. -
- -
Refreshing the current scene
- -
- Sometimes, it's useful to refresh the scene that is being played instead of stopping it and starting it again. This allows to bypass the export process - or the editor. Just click the refresh button -
- -
- located in the toolbar of the editor's preview panel. -
- -
- -
-
- -
-
+ + Introduction + +

+ Projects can be played directly from the editor. A project can be composed of multiple scenes and some scripts may be attached to objects in the scene(s). There are + 2 options: +

+ +
    +
  • + play the current scene: all the scripts are compiled on the fly and executed in the current scene that is displayed in the editor, sharing the same + resources (textures, etc.). This is the default behavior of the editor. +
    • +
  • + play the project as-is: consists on running the dev command using the project's selected package manager (npm, yarn, bun or pnpm). +
    • +
+ + Playing the current scene + +

+ To start the current scene, just click the start button located in the toolbar of the editor's preview + panel. +

+ +

+ Each time the current scene is played, the editor will update the assets located in the public folder of the project. If new assets were added to the project + (especially images), this can take a few seconds to generate all new necessary files before the project can be played. +

+ +

Note that when playing, all the scripts are watched for changes and will be reloaded automatically when modified until the "play" mode is stopped.

+ + Stopping the current scene + +

+ To stop the current scene being played and get back to the edit mode, just click the stop button located + in the toolbar of the editor's preview panel. +

+ + Refreshing the current scene + +

+ Sometimes, it's useful to refresh the scene that is being played instead of stopping it and starting it again. This allows to bypass the export process or the + editor. Just click the refresh button located in the toolbar of the editor's preview panel. +

+ + + ); } diff --git a/website/src/app/documentation/code.tsx b/website/src/app/documentation/code.tsx index 515eaf770..c6dae4971 100644 --- a/website/src/app/documentation/code.tsx +++ b/website/src/app/documentation/code.tsx @@ -1,55 +1,118 @@ "use client"; -import { useEffect, useRef } from "react"; - +import { useEffect, useRef, useState } from "react"; import { toast } from "sonner"; -import { FaCopy } from "react-icons/fa6"; - +import { Check, Copy } from "lucide-react"; import { codeToHtml } from "shiki"; export interface ICodeBlock { - language?: "typescript" | "bash" | "json"; - className?: string; code: string; + language?: "typescript" | "javascript" | "bash" | "json" | "html" | "css"; + filename?: string; + className?: string; } -export function CodeBlock(props: ICodeBlock) { +export function CodeBlock({ code, language = "typescript", filename, className = "" }: ICodeBlock) { const divRef = useRef(null); + const copyTimeout = useRef | null>(null); + const [copied, setCopied] = useState(false); + const [isReady, setIsReady] = useState(false); useEffect(() => { - handleCreateHtmlCode(); - }, [props.code, props.language]); + return () => { + if (copyTimeout.current) { + clearTimeout(copyTimeout.current); + } + }; + }, []); + + useEffect(() => { + let isMounted = true; + + setIsReady(false); - async function handleCreateHtmlCode() { - const html = await codeToHtml(props.code.trim(), { - lang: props.language || "typescript", - theme: "vitesse-dark", - }); + async function highlightCode() { + try { + const html = await codeToHtml(code.trim(), { + lang: language, + theme: "vitesse-dark", + }); - if (divRef.current) { - divRef.current.innerHTML = html; + if (isMounted && divRef.current) { + divRef.current.innerHTML = html; + setIsReady(true); + } + } catch { + // Fallback to plain text if language isn't supported + if (isMounted) { + setIsReady(false); + } + } } - } - async function handleCopyCode() { - await navigator.clipboard.writeText(props.code); - toast.success("Code copied to clipboard!"); + highlightCode(); + + return () => { + isMounted = false; + }; + }, [code, language]); + + async function handleCopyCode(codeSnippet: string) { + try { + await navigator.clipboard.writeText(codeSnippet); + setCopied(true); + toast.success("Code copied to clipboard!"); + if (copyTimeout.current) { + clearTimeout(copyTimeout.current); + } + copyTimeout.current = setTimeout(() => setCopied(false), 2000); + } catch { + toast.error("Failed to copy code."); + } } return ( -
-
{props.language ?? "typescript"}
-
- - +
+ {/* Code Header bar */} +
+
+ + + + {filename ? filename : language} +
+ + +
+ + {/* Code Container */} +
+
pre]:!bg-transparent [&>pre]:!p-0 [&>pre]:!m-0 ${isReady ? "block" : "hidden"}`} /> + + {/* Plaintext Fallback while Shiki is loading */} + {!isReady && ( + 
+						{code.trim()}
+
+ )} +
); } diff --git a/website/src/app/documentation/components/callout.tsx b/website/src/app/documentation/components/callout.tsx new file mode 100644 index 000000000..4ceff8d2a --- /dev/null +++ b/website/src/app/documentation/components/callout.tsx @@ -0,0 +1,72 @@ +import React, { PropsWithChildren, ReactNode } from "react"; +import { Info, Lightbulb, AlertTriangle, AlertOctagon, CheckCircle2 } from "lucide-react"; + +export type CalloutType = "note" | "tip" | "warning" | "caution" | "success" | "info"; + +export interface ICalloutProps extends PropsWithChildren { + type?: CalloutType; + title?: string; + icon?: ReactNode; + className?: string; +} + +const CALLOUT_STYLES: Record }> = { + note: { + border: "border-blue-500/30", + bg: "bg-blue-950/20", + text: "text-blue-400", + defaultTitle: "Note", + icon: Info, + }, + info: { + border: "border-sky-500/30", + bg: "bg-sky-950/20", + text: "text-sky-400", + defaultTitle: "Information", + icon: Info, + }, + tip: { + border: "border-emerald-500/30", + bg: "bg-emerald-950/20", + text: "text-emerald-400", + defaultTitle: "Tip", + icon: Lightbulb, + }, + warning: { + border: "border-amber-500/30", + bg: "bg-amber-950/20", + text: "text-amber-400", + defaultTitle: "Warning", + icon: AlertTriangle, + }, + caution: { + border: "border-rose-500/30", + bg: "bg-rose-950/20", + text: "text-rose-400", + defaultTitle: "Caution", + icon: AlertOctagon, + }, + success: { + border: "border-green-500/30", + bg: "bg-green-950/20", + text: "text-green-400", + defaultTitle: "Success", + icon: CheckCircle2, + }, +}; + +export function Callout({ type = "note", title, icon, children, className = "" }: ICalloutProps) { + const config = CALLOUT_STYLES[type] || CALLOUT_STYLES.note; + const IconComponent = config.icon; + const displayTitle = title ?? config.defaultTitle; + + return ( +
+
+ {icon ? icon : } + {displayTitle} +
+
{children}
+
+ ); +} diff --git a/website/src/app/documentation/components/doc-heading.tsx b/website/src/app/documentation/components/doc-heading.tsx new file mode 100644 index 000000000..b1914a135 --- /dev/null +++ b/website/src/app/documentation/components/doc-heading.tsx @@ -0,0 +1,76 @@ +import React, { PropsWithChildren, ReactNode, isValidElement } from "react"; +import { Link as LinkIcon } from "lucide-react"; + +export interface IDocHeadingProps extends PropsWithChildren { + level?: 2 | 3 | 4; + id?: string; + className?: string; +} + +function slugify(text: string): string { + return text + .toLowerCase() + .replace(/[@#]/g, "") + .replace(/[^a-z0-9]+/g, "-") + .replace(/^-+|-+$/g, ""); +} + +/** + * Recursively collects the textual content of a (possibly nested) React node, + * so headings containing inline JSX (e.g. ) still get a usable anchor id. + */ +function collectText(node: ReactNode): string { + if (node === null || node === undefined || typeof node === "boolean") { + return ""; + } + if (typeof node === "string" || typeof node === "number") { + return String(node); + } + if (Array.isArray(node)) { + return node.map(collectText).join(""); + } + if (isValidElement(node)) { + return collectText((node.props as { children?: ReactNode }).children); + } + return ""; +} + +export function DocHeading({ level = 2, id, children, className = "" }: IDocHeadingProps) { + const textContent = collectText(children); + const headingId = id || (textContent ? slugify(textContent) : undefined); + + const anchorLink = headingId ? ( + + + + ) : null; + + if (level === 2) { + return ( +

+ {children} + {anchorLink} +

+ ); + } + + if (level === 3) { + return ( +

+ {children} + {anchorLink} +

+ ); + } + + return ( +

+ {children} + {anchorLink} +

+ ); +} diff --git a/website/src/app/documentation/components/doc-media.tsx b/website/src/app/documentation/components/doc-media.tsx new file mode 100644 index 000000000..86de073f9 --- /dev/null +++ b/website/src/app/documentation/components/doc-media.tsx @@ -0,0 +1,41 @@ +import React from "react"; + +export interface IDocVideoProps { + src: string; + caption?: string; + autoPlay?: boolean; + loop?: boolean; + muted?: boolean; + controls?: boolean; + className?: string; +} + +export function DocVideo({ src, caption, autoPlay = true, loop = true, muted = true, controls = true, className = "" }: IDocVideoProps) { + return ( +
+
+
+ {caption &&
{caption}
} +
+ ); +} + +export interface IDocImageProps { + src: string; + alt?: string; + caption?: string; + className?: string; + imageClassName?: string; +} + +export function DocImage({ src, alt = "", caption, className = "", imageClassName = "" }: IDocImageProps) { + return ( +
+
+ {alt} +
+ {caption &&
{caption}
} +
+ ); +} diff --git a/website/src/app/documentation/components/doc-page.tsx b/website/src/app/documentation/components/doc-page.tsx new file mode 100644 index 000000000..300cc86a7 --- /dev/null +++ b/website/src/app/documentation/components/doc-page.tsx @@ -0,0 +1,50 @@ +"use client"; + +import React, { PropsWithChildren, ReactNode } from "react"; +import { usePathname } from "next/navigation"; +import { Fade } from "react-awesome-reveal"; +import { getDocItemByPath } from "../config"; +import { DocPagination } from "./doc-pagination"; + +export interface IDocPageProps extends PropsWithChildren { + /** Overrides the title from the documentation config. */ + title?: string; + /** Overrides the description from the documentation config. */ + description?: string; + headerActions?: ReactNode; + showPagination?: boolean; + className?: string; +} + +export function DocPage({ title, description, headerActions, showPagination = true, children, className = "" }: IDocPageProps) { + const pathname = usePathname(); + const configItem = getDocItemByPath(pathname); + + const displayTitle = title ?? configItem?.title; + const displayDescription = description ?? configItem?.description; + + return ( +
+
+ {/* Page Header */} + {(displayTitle || displayDescription || headerActions) && ( + +
+ {displayTitle &&

{displayTitle}

} + {displayDescription &&

{displayDescription}

} + {headerActions &&
{headerActions}
} +
+ + )} + + {/* Page Content */} + +
{children}
+ + + {/* Auto Pagination */} + {showPagination && } +
+
+ ); +} diff --git a/website/src/app/documentation/components/doc-pagination.tsx b/website/src/app/documentation/components/doc-pagination.tsx new file mode 100644 index 000000000..e8b420d82 --- /dev/null +++ b/website/src/app/documentation/components/doc-pagination.tsx @@ -0,0 +1,55 @@ +"use client"; + +import Link from "next/link"; +import { usePathname } from "next/navigation"; +import { ChevronLeft, ChevronRight } from "lucide-react"; +import { getAdjacentDocs } from "../config"; + +export interface IDocPaginationProps { + className?: string; +} + +export function DocPagination({ className = "" }: IDocPaginationProps) { + const pathname = usePathname(); + const { prev, next } = getAdjacentDocs(pathname); + + if (!prev && !next) { + return null; + } + + return ( +
+
+ {prev ? ( + +
+ + Previous +
+
{prev.title}
+ + ) : ( +
+ )} + + {next ? ( + +
+ Next + +
+
{next.title}
+ + ) : ( +
+ )} +
+
+ ); +} diff --git a/website/src/app/documentation/components/index.ts b/website/src/app/documentation/components/index.ts new file mode 100644 index 000000000..708ccd477 --- /dev/null +++ b/website/src/app/documentation/components/index.ts @@ -0,0 +1,7 @@ +export * from "./doc-page"; +export * from "./doc-heading"; +export * from "./doc-pagination"; +export * from "./callout"; +export * from "./doc-media"; +export * from "../code"; +export * from "../link"; diff --git a/website/src/app/documentation/config.ts b/website/src/app/documentation/config.ts new file mode 100644 index 000000000..d20e47dc6 --- /dev/null +++ b/website/src/app/documentation/config.ts @@ -0,0 +1,172 @@ +export interface IDocItem { + title: string; + href: string; + description?: string; +} + +export interface IDocCategory { + category: string; + items: IDocItem[]; +} + +export const DOCS_CONFIG: IDocCategory[] = [ + { + category: "Basics", + items: [ + { + title: "Introduction", + href: "/documentation", + description: "An overview of the Babylon.js Editor, what it can do, and what you need before getting started.", + }, + { + title: "Creating a project", + href: "/documentation/basics/creating-project", + description: "Learn how to create a new project, select project templates, configure package managers, and import existing projects in the editor.", + }, + { + title: "Composing scene", + href: "/documentation/basics/composing-scene", + description: "Learn the editor layout, select objects with gizmos, add primitives and 3D models, and manage the assets of your project.", + }, + { + title: "Managing assets", + href: "/documentation/basics/managing-assets", + description: "Create and edit your own materials, assign textures, and get the most out of the Assets Browser.", + }, + { + title: "Adding scripts", + href: "/documentation/basics/adding-scripts", + description: "Attach TypeScript scripts to scene objects and retrieve objects inside them using decorators.", + }, + { + title: "Running project", + href: "/documentation/basics/running-project", + description: "Play, stop, and refresh your scene directly from the editor without leaving the workspace.", + }, + ], + }, + { + category: "Scripting", + items: [ + { + title: "Common decorators", + href: "/documentation/scripting/common-decorators", + description: "Retrieve scene objects, components, animation groups, and asset containers directly inside attached scripts.", + }, + { + title: "Customizing scripts", + href: "/documentation/scripting/customizing-scripts", + description: "Expose script properties in the inspector with @visibleAs* decorators so each object can be configured individually.", + }, + { + title: "Listening events", + href: "/documentation/scripting/listening-events", + description: "Listen to pointer and keyboard events in attached scripts with @onPointerEvent and @onKeyboardEvent.", + }, + { + title: "Linking assets", + href: "/documentation/scripting/linking-assets", + description: "Reference JSON, material, and GUI assets from your scripts using @visibleAsAsset.", + }, + ], + }, + { + category: "Sprites", + items: [ + { + title: "Using Sprite Manager", + href: "/documentation/sprites/using-sprite-manager", + description: "Create sprite managers, configure textures and atlases, animate sprites, and attach scripts to them.", + }, + ], + }, + { + category: "Deploying", + items: [ + { + title: "Using Babylon.js Editor CLI", + href: "/documentation/deploying/babylonjs-editor-cli", + description: "Generate all project assets and scenes from the command line, ready to be used in your CI/CD pipeline.", + }, + ], + }, + { + category: "Plugins", + items: [ + { + title: "Using Fab Plugin", + href: "/documentation/plugins/fab", + description: "Import Fab.com assets directly into your project with the Fab plugin.", + }, + ], + }, + { + category: "Advanced", + items: [ + { + title: "Compressing textures", + href: "/documentation/advanced/compressing-textures", + description: "Reduce GPU memory usage with KTX and KTX2 compressed textures.", + }, + { + title: "LOD collisions", + href: "/documentation/advanced/lod-collisions", + description: "Upcoming: reduce collision computation cost with LOD-based colliders.", + }, + { + title: "Optimizing shadows", + href: "/documentation/advanced/optimizing-shadows", + description: "Upcoming: improve shadow rendering performance.", + }, + ], + }, + { + category: "Tips", + items: [ + { + title: "Shortcuts", + href: "/documentation/tips/shortcuts", + description: "All the keyboard shortcuts available in the editor.", + }, + { + title: "Creating a Skybox", + href: "/documentation/tips/creating-skybox", + description: "Build a skybox with a cube texture or a procedural Sky Material.", + }, + ], + }, +]; + +/** + * Returns a flat list of all documentation pages in sequential order. + */ +export function getAllDocItems(): IDocItem[] { + return DOCS_CONFIG.flatMap((cat) => cat.items); +} + +/** + * Returns the documentation entry matching the given pathname, if any. + */ +export function getDocItemByPath(pathname: string): IDocItem | undefined { + const cleanPath = pathname.replace(/\/$/, ""); + return getAllDocItems().find((item) => item.href === cleanPath || item.href === pathname); +} + +/** + * Returns the previous and next documentation pages relative to the current route. + */ +export function getAdjacentDocs(pathname: string): { prev: IDocItem | null; next: IDocItem | null } { + const allItems = getAllDocItems(); + // Normalize trailing slash if any + const cleanPath = pathname.replace(/\/$/, ""); + const index = allItems.findIndex((item) => item.href === cleanPath || item.href === pathname); + + if (index === -1) { + return { prev: null, next: null }; + } + + return { + prev: index > 0 ? allItems[index - 1] : null, + next: index < allItems.length - 1 ? allItems[index + 1] : null, + }; +} diff --git a/website/src/app/documentation/deploying/babylonjs-editor-cli/page.tsx b/website/src/app/documentation/deploying/babylonjs-editor-cli/page.tsx index 00ed46d8f..143fa2d7d 100644 --- a/website/src/app/documentation/deploying/babylonjs-editor-cli/page.tsx +++ b/website/src/app/documentation/deploying/babylonjs-editor-cli/page.tsx @@ -1,97 +1,76 @@ "use client"; -import Link from "next/link"; - -import { Fade } from "react-awesome-reveal"; - -import { CodeBlock } from "../../code"; +import { CodeBlock, CustomLink, DocPage, DocHeading, DocVideo } from "../../components"; import { ciExample, installing, pack, packageJson } from "./scripts"; export default function UsingBabylonJSEditorCLIPage() { return ( -
-
- - -
Using Babylon.js Editor CLI
- - - - -
-
Introduction
- -
- The Babylon.js Editor provides a package named babylonjs-editor-cli that can be installed as a dependency of a project. This package provides a - command line interface (CLI) to generate all necessary assets and files in the public/scene folder without having to open the editor application. -
- In other words, it allows you to generate all necessary assets in your own CI/CD pipeline. -
- -
- The package is available on NPM{" "} - - here - - . -
- -
- The goal of this CLI is to: -
    -
  • generate all .babylon scenes.
    • -
  • generate all necessary assets including down-scaled and compressed textures.
    • -
  • collect all scripts attached to entities in order to bundle them properly.
    • -
-
- -
Installing babylonjs-editor-cli
- -
- Starting from Babylon.js Editor v5.3.0, the babylonjs-editor-cli package is included as a dependency of newly generated projects. Therefore, if - you have created your project with a previous version of the editor, you will need to install it manually: -
- - - -
- Then, in your package.json, you can add a script to easily run the CLI: -
- - - -
Packing project
- -
- The babylonjs-editor-cli package provides a command named pack that will generate all necessary assets and files in the public/scene{" "} - folder of your project. -
- To run the command, simply use: -
- - - -
A cache is automatically saved locally in order to speed up the packing process on subsequent runs.
- -
- -
- -
- The pack command will also collect all scripts attached to entities in order to bundle them properly. -
- It is IMPORTANT to pack the project before building it so that all scripts (located at src/scripts.ts) are properly bundled. -
- -
Here is a simple example on how the CI/CD pipeline could look like:
- - -
- + + Introduction + +

+ The Babylon.js Editor provides a package named babylonjs-editor-cli that can be installed as a dependency of a project. This package provides a command line + interface (CLI) to generate all necessary assets and files in the public/scene folder without having to open the editor application. +
+ In other words, it allows you to generate all necessary assets in your own CI/CD pipeline. +

+ +

+ The package is available on NPM here. +

+ +
+

The goal of this CLI is to:

+ +
    +
  • + generate all .babylon scenes. +
    • +
  • generate all necessary assets including down-scaled and compressed textures.
    • +
  • collect all scripts attached to entities in order to bundle them properly.
    • +
-
+ + Installing babylonjs-editor-cli + +

+ Starting from Babylon.js Editor v5.3.0, the babylonjs-editor-cli package is included as a dependency of newly generated projects. Therefore, if you have + created your project with a previous version of the editor, you will need to install it manually: +

+ + + +

+ Then, in your package.json, you can add a script to easily run the CLI: +

+ + + + Packing project + +

+ The babylonjs-editor-cli package provides a command named pack that will generate all necessary assets and files in the public/scene folder of your + project. +
+ To run the command, simply use: +

+ + + +

A cache is automatically saved locally in order to speed up the packing process on subsequent runs.

+ + + +

+ The pack command will also collect all scripts attached to entities in order to bundle them properly. +
+ It is IMPORTANT to pack the project before building it so that all scripts (located at src/scripts.ts) are properly bundled. +

+ +

Here is a simple example on how the CI/CD pipeline could look like:

+ + + ); } diff --git a/website/src/app/documentation/next-chapter.tsx b/website/src/app/documentation/next-chapter.tsx deleted file mode 100644 index 9b37fb49e..000000000 --- a/website/src/app/documentation/next-chapter.tsx +++ /dev/null @@ -1,29 +0,0 @@ -"use client"; - -import Link from "next/link"; - -import { GrNext } from "react-icons/gr"; - -export interface INextChapterComponentProps { - href: string; - title: string; -} - -export function NextChapterComponent(props: INextChapterComponentProps) { - return ( - -
- -
-
- - -
-
Next
-
{props.title}
-
-
-
- - ); -} diff --git a/website/src/app/documentation/page.tsx b/website/src/app/documentation/page.tsx index 329fe1577..1941f8686 100644 --- a/website/src/app/documentation/page.tsx +++ b/website/src/app/documentation/page.tsx @@ -1,87 +1,44 @@ "use client"; -import Link from "next/link"; - -import { Fade } from "react-awesome-reveal"; - -import { NextChapterComponent } from "./next-chapter"; +import { Callout, CustomLink, DocPage, DocHeading } from "./components"; export default function DocumentationPage() { return ( -
-
- - -
Babylon.js Editor documentation
- - - - -
-
Introduction
- -
- Babylon.js Editor is a visual editor for Babylon.js. It allows you to create and edit scenes, materials, attach scripts and more. -
- The Babylon.js Editor is available on Window, macOS, and Linux platforms. -
- -
- The goal is to provide a simple and easy-to-use interface for creating and editing Babylon.js applications such as video games. It includes a large - variety of optimization tools, such as compressed textures generation, LOD collisions and more. -
- -
- The Babylon.js Editor is free and open-source. You can find the source code on{" "} - - - GitHub - - - . -
- -
Prerequisite
- -
- - - Node.JS - - {" "} - must be installed on your computer. It is recommanded to have LTS version installed {">="} 20 -
- -
- By default, projects are based on Next.JS. It is highly recommanded to have a basic understanding of{" "} - - - React - - {" "} - and{" "} - - - Next.JS - - {" "} - before starting. -
- -
- Of course, a basic understanding of the{" "} - - - Babylon.js - - {" "} - engine. The most powerful, beautiful, simple, and open web rendering engine in the world. -
- - -
- -
-
+ + Introduction + +

+ Babylon.js Editor is a visual editor for Babylon.js. It allows you to create and edit scenes, materials, attach scripts and more. +
+ The Babylon.js Editor is available on Windows, macOS, and Linux platforms. +

+ +

+ The goal is to provide a simple and easy-to-use interface for creating and editing Babylon.js applications such as video games. It includes a large variety of + optimization tools, such as compressed textures generation, LOD collisions and more. +

+ +

+ The Babylon.js Editor is free and open-source. You can find the source code on{" "} + + GitHub + + . +

+ + Prerequisites + +

+ Node.js must be installed on your computer. It is recommended to have an LTS version {">="} 20. +

+ + + By default, projects are based on Next.js. It is highly recommended to have a basic understanding of React{" "} + and Next.js before starting. +
+ Of course, also a basic understanding of the Babylon.js engine, the most powerful, beautiful, simple, and + open web rendering engine in the world. + + ); } diff --git a/website/src/app/documentation/plugins/fab/page.tsx b/website/src/app/documentation/plugins/fab/page.tsx index 8d825791a..e67b8d5ab 100644 --- a/website/src/app/documentation/plugins/fab/page.tsx +++ b/website/src/app/documentation/plugins/fab/page.tsx @@ -1,122 +1,91 @@ "use client"; -import Link from "next/link"; -import { Fade } from "react-awesome-reveal"; +import { Callout, CustomLink, DocPage, DocHeading, DocVideo } from "../../components"; -export default function DocumentationCreatingSkyboxPage() { +export default function DocumentationUsingFabPluginPage() { return ( -
-
- - -
Using Fab Plugin
- - - - -
-
Introduction
- -
- - Fab.com - {" "} - is a tool-agnostic marketplace for digital assets created by{" "} - - Epic Games - - . It allows creators to sell 3D models, textures, and other digital assets to a wide audience. -
- Download an asset from Fab and export it to your favorite software. The Fab plugin for Babylon.js Editor allows you to import these assets directly into - your project. -
- -
Prerequisite
- -
- In order to use Fab and download/export assets, you need an active Epic Games account and the Epic Games Launcher installed on your - computer. -
- -
Installing the plugin
- -
- The Babylon.js Editor Fab plugin is available as a{" "} - - npm package - - . To install a plugin, simply open the Project Settings in the Babylon.js Editor, go to the Plugins tab, click the Add button and - select From npm. -
- -
- Then enter the name of the plugin to add. The name of the Fab plugin is babylonjs-editor-fab-plugin. -
- -
- Once installed, a new tab named Fab will be available in the Editor's layout. This tab will show all the assets that were exported using Fab and - can be imported into the current project. -
- -
- -
- -
Importing
- -
- For now, suported asset types are: -
    -
  • For 3D models: GLTF, GLB, OBJ and FBX.
    • -
  • For materials: Texture Set
    • -
-
- -
- To import assets from Fab, download any asset from the Fab section in the Epic Games Launcher by selecting the right file format before and - select the Export target to be Custom (socket port). Once done, simply click the Export button. -
- -
- Note: in case of a collection of multiple assets, Fab will ask you if you want to export all assets. All assets will be imported in the project's root - folder assets/fab and any unused assets can be deleted later. -
- -
- Once exported, the Editor will perform all necessary conversions and optimizations for assets such as the merge of textures for metallic-roughness - materials (ORM) etc. According to the size of the asset(s), this process can take a few seconds to a couple of minutes. -
- -
- -
- -
Instantiating
- -
- To instantiate an imported Fab asset into the scene, simply select it from the Fab tab and drag'n'drop it into the preview panel like any other asset. -
- Because Fab assets are described by a collection of meshes and materials, the plugin will automatically assign pre-configured materials to the meshes - when instantiating them. -
- -
- For a manual import, you can simply navigate to the assets/fab folder in the Assets browser panel and drag'n'drop the desired asset into - the preview or the graph panels. Doing that allows you to use available assets such as materials separately. -
- -
- -
-
- + + Introduction + +

+ Fab.com is a tool-agnostic marketplace for digital assets created by{" "} + Epic Games. It allows creators to sell 3D models, textures, and other digital assets to a wide audience. +
+ Download an asset from Fab and export it to your favorite software. The Fab plugin for Babylon.js Editor allows you to import these assets directly into your + project. +

+ + Prerequisites + +

+ In order to use Fab and download/export assets, you need an active Epic Games account and the Epic Games Launcher installed on your computer. +

+ + Installing the plugin + +

+ The Babylon.js Editor Fab plugin is available as a{" "} + + npm package + + . To install a plugin, simply open the Project Settings in the Babylon.js Editor, go to the Plugins tab, click the Add button and select{" "} + From npm. +

+ +

+ Then enter the name of the plugin to add. The name of the Fab plugin is babylonjs-editor-fab-plugin. +

+ +

+ Once installed, a new tab named Fab will be available in the Editor's layout. This tab will show all the assets that were exported using Fab and can be + imported into the current project. +

+ + + + Importing + +
+

For now, supported asset types are:

+ +
    +
  • For 3D models: GLTF, GLB, OBJ and FBX.
    • +
  • For materials: Texture Set
    • +
-
+ +

+ To import assets from Fab, download any asset from the Fab section in the Epic Games Launcher by selecting the right file format before and select the{" "} + Export target to be Custom (socket port). Once done, simply click the Export button. +

+ + + In case of a collection of multiple assets, Fab will ask you if you want to export all assets. All assets will be imported in the project's root folder{" "} + assets/fab and any unused assets can be deleted later. + + +

+ Once exported, the Editor will perform all necessary conversions and optimizations for assets such as the merge of textures for metallic-roughness materials (ORM) + etc. According to the size of the asset(s), this process can take a few seconds to a couple of minutes. +

+ + + + Instantiating + +

+ To instantiate an imported Fab asset into the scene, simply select it from the Fab tab and drag'n'drop it into the preview panel like any other asset. +
+ Because Fab assets are described by a collection of meshes and materials, the plugin will automatically assign pre-configured materials to the meshes when + instantiating them. +

+ +

+ For a manual import, you can simply navigate to the assets/fab folder in the Assets browser panel and drag'n'drop the desired asset into the preview + or the graph panels. Doing that allows you to use available assets such as materials separately. +

+ + + ); } diff --git a/website/src/app/documentation/scripting/common-decorators/page.tsx b/website/src/app/documentation/scripting/common-decorators/page.tsx index a48630eff..e58bae185 100644 --- a/website/src/app/documentation/scripting/common-decorators/page.tsx +++ b/website/src/app/documentation/scripting/common-decorators/page.tsx @@ -1,120 +1,81 @@ "use client"; -import { Fade } from "react-awesome-reveal"; - -import { CodeBlock } from "../../code"; - +import { DocPage, DocHeading, CodeBlock, Callout, CustomLink } from "../../components"; import { animationGroupFromScene, componentFromScene, nodeFromDescendants, nodeFromScene, sceneAsset } from "./decorators"; -import { CustomLink } from "../../link"; export default function DocumentationCommonDecoratorsPage() { return ( -
-
- - -
Common decorators
- - - - -
-
Introduction
- -
- Scripts can retrieve instances from the scene by using some common decorators. Those decorators are used to retrieve objects from the scene and link - them to properties in the script. This way, you can easily reference other objects in the scene and use them in your script. -
- - {/* Node from scene */} -
@nodeFromScene
- -
- This decorator is used to retrieve any Mesh, TransformNode, Light or Camera from the scene by its name. The retrieved node - is linked to the decorated property, so you can use it in your script. -
- - - - {/* Node from descendants */} -
@nodeFromDescendants
- -
- This decorator is used to retrieve any Mesh, TransformNode, Light or Camera from the children of the object the - script is attached to. The retrieved node is linked to the decorated property, so you can use it in your script. -
- - - - {/* Animation group */} -
@animationGroupFromScene
- -
- This decorator is used to retrieve any Animation Group from the scene. The retrieved animation group is linked to the decorated property, so you - can use it in your script. -
- - - - {/* Scene asset */} -
@sceneAsset
- -
This decorator is used to load and retrieve a scene container.
- -
- A scene can be used for multiple reasons. For example, a scene that is used once like a map, or a scene that is set to be instantiated multiple times - like an enemies. In the first case, you can load the scene and retrieve the container with the decorator, while in the second case, you can load the - scene as a container and instantiate it multiple times in the main scene. -
- -
- The retrieved scene container instance is of type AdvancedAssetContainer, which is an extended version of the AssetContainer class - provided by Babylon.js. -
- -
- A scene container can be used to instantiate the assets multiple time. The goal of the AdvancedAssetContainer is to add support of extra features - to the default AssetContainer, like the possibility instantiate attached scripts to instantiated entries. -
- -
- Available methods are: -
    -
  • - removeDefault: When a scene is loaded as a container, it is automatically instantiated once and the instances are added to the main - scene. This method allows to remove those default instances from the main scene as the container is used to be instantiated on-demand, for - example for enemies. -
    • -
  • - instantiate: Instantiates the whole container and returns the root nodes of the instantiated hierarchy. More information about - instantiated entries in{" "} - - Babylon.js Documentation (Duplicating the models) - -
    • -
-
- - - - {/* Component from scene */} -
@componentFromScene
- -
- This decorator is used to retrieve the unique reference to a script attached to an object that has been instantiated in the scene. The retrieved script - reference is linked to the decorated property, so you can use it in your script. -
- -
- When using this decorator, make sure that only one instance of the script you want to retrieve is attached to objects in the scene. If multiple - instances of the same script are found in the scene, an error will be thrown and the project won't be able to run, since it won't know which one to link - to. -
- - -
- + + Introduction + +

+ Scripts can retrieve instances from the scene by using common decorators. Those decorators link scene objects directly to properties in your script, making it + simple to reference meshes, lights, cameras, or other components without manual searching. +

+ + @nodeFromScene + +

+ Retrieves any Mesh, TransformNode, Light, or Camera from the scene by its name. The retrieved node is linked directly to the decorated + property. +

+ + + + @nodeFromDescendants + +

+ Retrieves any Mesh, TransformNode, Light, or Camera from the children of the object the script is attached to. +

+ + + + @animationGroupFromScene + +

+ Retrieves any Animation Group from the scene by name. +

+ + + + @sceneAsset + +

Loads and retrieves a scene container. This is useful for reusable assets like maps or enemies that need to be instantiated multiple times on demand.

+ +

+ The retrieved instance is of type AdvancedAssetContainer, which extends the Babylon.js AssetContainer class to support attaching scripts to + instantiated entries. +

+ +
+

Available methods:

+
    +
  • + removeDefault: When a scene container is loaded, it is automatically instantiated once. Calling this removes those default instances from the scene + so you can instantiate them strictly on demand. +
    • +
  • + instantiate: Instantiates the container and returns the root nodes. Learn more in the{" "} + + Babylon.js Documentation (Duplicating the models) + + . +
    • +
-
+ + + + @componentFromScene + +

Retrieves the unique reference to a script attached to an object in the scene.

+ + + Make sure that only one instance of the target script is attached in the scene. If multiple instances are found, an error is thrown because the editor cannot + determine which instance to link. + + + + ); } diff --git a/website/src/app/documentation/scripting/customizing-scripts/page.tsx b/website/src/app/documentation/scripting/customizing-scripts/page.tsx index e6c1e18c8..b19e1c10e 100644 --- a/website/src/app/documentation/scripting/customizing-scripts/page.tsx +++ b/website/src/app/documentation/scripting/customizing-scripts/page.tsx @@ -1,8 +1,6 @@ "use client"; -import { Fade } from "react-awesome-reveal"; - -import { CodeBlock } from "../../code"; +import { CodeBlock, DocPage, DocHeading, DocVideo } from "../../components"; import { visibleAsBooleanDecoratorsExample, @@ -15,178 +13,168 @@ import { visibleAsVector3DecoratorsExample, } from "./visible-as"; -export default function DocumentationRunningProjectPage() { +export default function DocumentationCustomizingScriptsPage() { return ( -
-
- - -
Customizing scripts
- - - - -
-
Introduction
- -
- A same script can be attached to multiple objects in the scene. Each object may have its own configuration for the script so they can behave - differently. To do so, properties like booleans, numbers, vectors, colors etc. can be decorated so they become customizable in the editor per script and - per object. -
- -
- Each decorator is composed of at least a label and an optional description. This label is used to be displayed in the editor (if not provided, the name - of the property is used as a label), where the description is used as a tooltip to help the user to understand what's the purpose of the property. -
- -
@visibleAsBoolean
- -
- When a property is decorated with @visibleAsBoolean, it will be displayed as a checkbox in the editor's inspector. This field can be customized - with a label that is the first parameter of the decorator and a description. -
- - - -
@visibleAsNumber
- -
- When a property is decorated with @visibleAsNumber, it will be displayed as a number field in the editor's inspector. This field can be - customized with: -
    -
  • - min: Defines the minimum value the user can set (optional). -
    • -
  • - max: Defines the maximum value the user can set (optional). -
    • -
  • - step: Defines the increment/decrement step value (when the user slides on the input, optional). -
    • -
-
- - - -
@visibleAsString
- -
- When a property is decorated with @visibleAsString, it will be displayed as a text input in the editor's inspector. This field can be customized - with a label that is the first parameter of the decorator and a description. -
- - - -
@visibleAsVector2
- -
- When a property is decorated with @visibleAsVector2, it will be displayed as a 2D vector field (X and Y) in the editor's inspector. This field - can be customized with: -
    -
  • - min: Defines the minimum value the user can set for each axis (optional). -
    • -
  • - max: Defines the maximum value the user can set for each axis (optional). -
    • -
  • - step: Defines the increment/decrement step value (when the user slides on the input, optional). -
    • -
  • - asDegrees: Defines if the field should convert radians to degrees internally for a better understanding (optional). -
    • -
-
- - - -
@visibleAsVector3
- -
- When a property is decorated with @visibleAsVector3, it will be displayed as a 3D vector field (X, Y and Z) in the editor's inspector. Properties - to customize the field are the same as for @visibleAsVector2. -
- - - -
@visibleAsColor3
- -
- When a property is decorated with @visibleAsColor3, it will be displayed as a color field (R, G and B) in the editor's inspector. The color field - has a color picker added automatically by default. -
- -
- This field can be customized with: -
    -
  • - noClamp: Defines if the color values (R, G and B) should be clamped between 0 and 1 (optional). -
    • -
  • - noColorPicker: Defines if the color picker should be disabled (optional). -
    • -
-
- - - -
@visibleAsColor4
- -
- When a property is decorated with @visibleAsColor4, it will be displayed as a color field (R, G, B and A for the alpha) in the editor's - inspector. Properties to customize the field are the same as for @visibleAsColor3. -
- - - -
@visibleAsEntity
- -
- When a property is decorated with @visibleAsEntity, it will be displayed as a field that can receive entities from the scene in the editor's - inspector. This creates a link to the chosen entity and allows to retrieve it in the script. -
- -
To set an entity, simply select it in the graph of the editor and drag it to the field.
- -
- The type of entities that can be dropped on the field are, according to the configuration of the decorator: -
    -
  • - node: Any node from Babylon.js like meshes, cameras, lights, transform nodes, etc. that is available in the scene. -
    • -
  • - sound: Any sound that has been instantiated and available in the scene. -
    • -
  • - particleSystem: Any particle system that is available in the scene. -
    • -
  • - animationGroup: Any animation group that is available in the scene. -
    • -
-
- - - -
- Let's have a scene with 2 boxes: one has a script attached to it and the second one is just a mesh. The first box has a script that rotates the entity - that is attached to it using the @visibleAsEntity decorator. -
- -
- In this example, the second box is attached to the first box's script so the rotation of the second box will be updated by the script when running the - scene. The entity is attached just by drag'n'dropping it in the inspector's field. -
- -
- -
-
- + + Introduction + +

+ A same script can be attached to multiple objects in the scene. Each object may have its own configuration for the script so they can behave differently. To do so, + properties like booleans, numbers, vectors, colors etc. can be decorated so they become customizable in the editor per script and per object. +

+ +

+ Each decorator is composed of at least a label and an optional description. This label is used to be displayed in the editor (if not provided, the name of the + property is used as a label), where the description is used as a tooltip to help the user to understand what's the purpose of the property. +

+ + @visibleAsBoolean + +

+ When a property is decorated with @visibleAsBoolean, it will be displayed as a checkbox in the editor's inspector. This field can be customized with a label + that is the first parameter of the decorator and a description. +

+ + + + @visibleAsNumber + +
+

+ When a property is decorated with @visibleAsNumber, it will be displayed as a number field in the editor's inspector. This field can be customized with: +

+ +
    +
  • + min: defines the minimum value the user can set (optional). +
    • +
  • + max: defines the maximum value the user can set (optional). +
    • +
  • + step: defines the increment/decrement step value (when the user slides on the input, optional). +
    • +
+
+ + + + @visibleAsString + +

+ When a property is decorated with @visibleAsString, it will be displayed as a text input in the editor's inspector. This field can be customized with a label + that is the first parameter of the decorator and a description. +

+ + + + @visibleAsVector2 + +
+

+ When a property is decorated with @visibleAsVector2, it will be displayed as a 2D vector field (X and Y) in the editor's inspector. This field can be + customized with: +

+ +
    +
  • + min: defines the minimum value the user can set for each axis (optional). +
    • +
  • + max: defines the maximum value the user can set for each axis (optional). +
    • +
  • + step: defines the increment/decrement step value (when the user slides on the input, optional). +
    • +
  • + asDegrees: defines if the field should convert radians to degrees internally for a better understanding (optional). +
    • +
+
+ + + + @visibleAsVector3 + +

+ When a property is decorated with @visibleAsVector3, it will be displayed as a 3D vector field (X, Y and Z) in the editor's inspector. Properties to + customize the field are the same as for @visibleAsVector2. +

+ + + + @visibleAsColor3 + +

+ When a property is decorated with @visibleAsColor3, it will be displayed as a color field (R, G and B) in the editor's inspector. The color field has a color + picker added automatically by default. +

+ +
+

This field can be customized with:

+ +
    +
  • + noClamp: defines if the color values (R, G and B) should be clamped between 0 and 1 (optional). +
    • +
  • + noColorPicker: defines if the color picker should be disabled (optional). +
    • +
+
+ + + + @visibleAsColor4 + +

+ When a property is decorated with @visibleAsColor4, it will be displayed as a color field (R, G, B and A for the alpha) in the editor's inspector. Properties + to customize the field are the same as for @visibleAsColor3. +

+ + + + @visibleAsEntity + +

+ When a property is decorated with @visibleAsEntity, it will be displayed as a field that can receive entities from the scene in the editor's inspector. This + creates a link to the chosen entity and allows to retrieve it in the script. +

+ +

To set an entity, simply select it in the graph of the editor and drag it to the field.

+ +
+

The type of entities that can be dropped on the field are, according to the configuration of the decorator:

+ +
    +
  • + node: any node from Babylon.js like meshes, cameras, lights, transform nodes, etc. that is available in the scene. +
    • +
  • + sound: any sound that has been instantiated and available in the scene. +
    • +
  • + particleSystem: any particle system that is available in the scene. +
    • +
  • + animationGroup: any animation group that is available in the scene. +
    • +
-
+ + + +

+ Let's have a scene with 2 boxes: one has a script attached to it and the second one is just a mesh. The first box has a script that rotates the entity that is + attached to it using the @visibleAsEntity decorator. +

+ +

+ In this example, the second box is attached to the first box's script so the rotation of the second box will be updated by the script when running the scene. The + entity is attached just by drag'n'dropping it in the inspector's field. +

+ + + ); } diff --git a/website/src/app/documentation/scripting/linking-assets/page.tsx b/website/src/app/documentation/scripting/linking-assets/page.tsx index b395530d9..13ef6be84 100644 --- a/website/src/app/documentation/scripting/linking-assets/page.tsx +++ b/website/src/app/documentation/scripting/linking-assets/page.tsx @@ -1,103 +1,81 @@ "use client"; -import { Fade } from "react-awesome-reveal"; -import { IoIosWarning } from "react-icons/io"; - -import { CodeBlock } from "../../code"; +import { Callout, CodeBlock, DocPage, DocHeading, DocVideo } from "../../components"; import { linkingGuiExample, linkingJsonExample, linkingMaterialExample, linkingRestrictedMaterialExample } from "./code"; export default function DocumentationLinkingAssetsPage() { return ( -
-
- - -
Linking assets
- - - - -
-
Introduction
- -
The editor provides a way to use assets directly in scripts. Those assets are preloaded and are part the loading process of the scene.
- -
- To use those assets in scripts, properties need to be decorated with the @visibleAsAsset decorator from the babylonjs-editor-tools package - and will then be available in the editor's inspector. -
- To set those properties, simply select an asset from the Assets Browser panel and drag & drop it to the desired property in the inspector. -
- -
If the dropped asset is not compatible with the property type, an error popin will be displayed.
- -
- The supported asset types are: -
    -
  • - json: any JSON file that can be parsed. -
    • -
  • - material: any material created in the editor and available as asset. -
    • -
  • - gui: any GUI created in the editor and available as asset. -
    • -
-
- -
- -
- -
- - -
- Those decorators are available in the babylonjs-editor-tools package that is provided as a depdendency in the package.json file. In - case a decorator that is documented here is not available in the code, make sure to install the up-to-date package in your project. -
-
- -
JSON files
- -
- When a property is decorated with @visibleAsAsset, this property will be linked to the provided asset with extension .json in the editor's - inspector. The JSON file is automatically parsed and properties can be accessed directly. -
- - - -
Material files
- -
- As well as JSON files, when a property is decorated with @visibleAsAsset, this property will be linked to the provided asset with extension{" "} - .material in the editor's inspector. The material is automatically parsed and properties can be accessed directly. -
- - - -
- In order to restrict the type of supported material, a configuration object can be passed to the decorator. By default, all materials are allowed. - Example to restrict to PBR material: -
- - - -
GUI files
- -
- As well as JSON files, when a property is decorated with @visibleAsAsset, this property will be linked to the provided asset with extension{" "} - .gui in the editor's inspector. The GUI file is automatically parsed and properties can be accessed directly. -
- - -
- + + Introduction + +

The editor provides a way to use assets directly in scripts. Those assets are preloaded and are part of the loading process of the scene.

+ +

+ To use those assets in scripts, properties need to be decorated with the @visibleAsAsset decorator from the babylonjs-editor-tools package and will + then be available in the editor's inspector. +
+ To set those properties, simply select an asset from the Assets Browser panel and drag & drop it to the desired property in the inspector. +

+ +

If the dropped asset is not compatible with the property type, an error popup will be displayed.

+ +
+

The supported asset types are:

+ +
    +
  • + json: any JSON file that can be parsed. +
    • +
  • + material: any material created in the editor and available as asset. +
    • +
  • + gui: any GUI created in the editor and available as asset. +
    • +
-
+ + + + + Those decorators are available in the babylonjs-editor-tools package that is provided as a dependency in the package.json file. In case a decorator + that is documented here is not available in the code, make sure to install the up-to-date package in your project. + + + JSON files + +

+ When a property is decorated with @visibleAsAsset, this property will be linked to the provided asset with extension .json in the editor's inspector. + The JSON file is automatically parsed and properties can be accessed directly. +

+ + + + Material files + +

+ As well as JSON files, when a property is decorated with @visibleAsAsset, this property will be linked to the provided asset with extension .material{" "} + in the editor's inspector. The material is automatically parsed and properties can be accessed directly. +

+ + + +

+ In order to restrict the type of supported material, a configuration object can be passed to the decorator. By default, all materials are allowed. Example to + restrict to PBR material: +

+ + + + GUI files + +

+ As well as JSON files, when a property is decorated with @visibleAsAsset, this property will be linked to the provided asset with extension .gui in + the editor's inspector. The GUI file is automatically parsed and properties can be accessed directly. +

+ + + ); } diff --git a/website/src/app/documentation/scripting/listening-events/page.tsx b/website/src/app/documentation/scripting/listening-events/page.tsx index ec9dddde6..13ae3a4d6 100644 --- a/website/src/app/documentation/scripting/listening-events/page.tsx +++ b/website/src/app/documentation/scripting/listening-events/page.tsx @@ -1,9 +1,6 @@ "use client"; -import { Fade } from "react-awesome-reveal"; -import { IoIosWarning } from "react-icons/io"; - -import { CodeBlock } from "../../code"; +import { Callout, CodeBlock, DocPage, DocHeading } from "../../components"; import { onPointerEventBasicExample, @@ -14,117 +11,90 @@ import { onKeyboardEventArrayBasicExample, } from "./code"; -export default function DocumentationRunningProjectPage() { +export default function DocumentationListeningEventsPage() { return ( -
-
- - -
Listening events
- - - - -
-
Introduction
- -
- The editor provides some helpers for listening events in the scene. Those helpers are provided as decorators and can be used in any attached script in - the scene. -
- -
- Each decorator can be used to decorate a method in the class. Method that will be called each time an event of the provided type(s) is raised in the - scene. -
+ + Introduction -
- +

The editor provides some helpers for listening events in the scene. Those helpers are provided as decorators and can be used in any attached script in the scene.

-
- Those decorators are available in the babylonjs-editor-tools package that is provided as a depdendency in the package.json file. In - case a decorator that is documented here is not available in the code, make sure to install the up-to-date package in your project. -
-
+

Each decorator can be used to decorate a method in the class. Method that will be called each time an event of the provided type(s) is raised in the scene.

-
@onPointerEvent
+ + Those decorators are available in the babylonjs-editor-tools package that is provided as a dependency in the package.json file. In case a decorator + that is documented here is not available in the code, make sure to install the up-to-date package in your project. + -
- When a method is decorated with @onPointerEvent, this method will be called each time the provided pointer event type(s) is raised in the scene: -
+ @onPointerEvent - +

+ When a method is decorated with @onPointerEvent, this method will be called each time the provided pointer event type(s) is raised in the scene: +

-
- Multiple event types can be listened at the same time by providing an array of event types to the decorator. -
- The decorated method always receives a parameter of type PointerInfo that contains more information about the event that has been raised. -
+ - +

+ Multiple event types can be listened at the same time by providing an array of event types to the decorator. +
+ The decorated method always receives a parameter of type PointerInfo that contains more information about the event that has been raised. +

-
Filtering per mesh
+ -
- By default, the @onPointerEvent decorator listens for global events. In other words, anywhere the pointer event is raised in the scene, the decorated - method will be called. -
+ Filtering per mesh -
- Scripts that are attached to meshes (extending AbstractMesh class) can listen for events that are raised only on the attached mesh by changing - the listening mode. -
+

+ By default, the @onPointerEvent decorator listens for global events. In other words, anywhere the pointer event is raised in the scene, the decorated method + will be called. +

-
- +

+ Scripts that are attached to meshes (extending AbstractMesh class) can listen for events that are raised only on the attached mesh by changing the listening + mode. +

-
- The following mode is only available for scripts attached to meshes. If the attached object is not a Mesh then an error will be thrown at runtime - when loading the scene. -
-
+ + The following mode is only available for scripts attached to meshes. If the attached object is not a Mesh then an error will be thrown at runtime when loading the + scene. + - + -
Including descendants
+ Including descendants -
- When importing meshes, from a GLB files for example, it can be useful to listen for events on the entire hierarchy of imported meshes. Especially - when the imported hierarchy is complex and contains multiple meshes. -
+

+ When importing meshes, from a GLB file for example, it can be useful to listen for events on the entire hierarchy of imported meshes. Especially when the + imported hierarchy is complex and contains multiple meshes. +

-
- To do so, the listening mode can be set to includeDescendants and the decorated method will be called when the event is raised on the attached - mesh or any of its descendants. -
+

+ To do so, the listening mode can be set to includeDescendants and the decorated method will be called when the event is raised on the attached mesh or any of + its descendants. +

-
- That way, this mode is available on any node (TransformNode, Light, etc.) the script is attached to and is not limited to meshes only like the mode{" "} - attachedMeshOnly. -
+

+ That way, this mode is available on any node (TransformNode, Light, etc.) the script is attached to and is not limited to meshes only like the mode{" "} + attachedMeshOnly. +

- + -
@onKeyboardEvent
+ @onKeyboardEvent -
- As well as @onPointerEvent decorator, the editor provides a @onKeyboardEvent decorator that can be used to listen for keyboard events in - the scene. -
+

+ As well as the @onPointerEvent decorator, the editor provides a @onKeyboardEvent decorator that can be used to listen for keyboard events in the + scene. +

-
- When a method is decorated with @onKeyboardEvent, this method will be called each time the provided keyboard event type(s) is raised in the - scene: -
+

+ When a method is decorated with @onKeyboardEvent, this method will be called each time the provided keyboard event type(s) is raised in the scene: +

- + -
As well as for pointer events, multiple event types can be listened at the same time by providing an array of event types to the decorator:
+

As well as for pointer events, multiple event types can be listened at the same time by providing an array of event types to the decorator:

- -
- -
-
+ + ); } diff --git a/website/src/app/documentation/sidebar.tsx b/website/src/app/documentation/sidebar.tsx index dcae6e236..a7e8b4497 100644 --- a/website/src/app/documentation/sidebar.tsx +++ b/website/src/app/documentation/sidebar.tsx @@ -2,11 +2,11 @@ import Link from "next/link"; import { usePathname } from "next/navigation"; +import { DOCS_CONFIG } from "./config"; export interface IDocumentationSidebarItemProps { href: string; title: string; - className?: string; } @@ -16,7 +16,7 @@ export function DocumentationSidebarItem(props: IDocumentationSidebarItemProps) return ( {props.title} @@ -27,45 +27,14 @@ export function DocumentationSidebar() { return (
-
Basics
- - - - - - - - -
Scripting
- - - - - - -
Assets
- - - - -
Deploying
- - - -
Plugins
- - - -
Advanced
- - - - - -
Tips
- - - + {DOCS_CONFIG.map((category) => ( +
+
{category.category}
+ {category.items.map((item) => ( + + ))} +
+ ))}
); diff --git a/website/src/app/documentation/tips/creating-skybox/page.tsx b/website/src/app/documentation/tips/creating-skybox/page.tsx index d1fbba503..2a46ed599 100644 --- a/website/src/app/documentation/tips/creating-skybox/page.tsx +++ b/website/src/app/documentation/tips/creating-skybox/page.tsx @@ -1,128 +1,86 @@ "use client"; -import Link from "next/link"; - -import { Fade } from "react-awesome-reveal"; import { FaArrowRight } from "react-icons/fa6"; +import { CustomLink, DocPage, DocHeading, DocImage, DocVideo } from "../../components"; + export default function DocumentationCreatingSkyboxPage() { return ( -
-
- - -
Creating a Skybox
- - - - -
-
Introduction
- -
- A simulated sky can be added to a scene using a "skybox" ( - - Wikipedia - - ). A skybox is a large standard cube surrounding the scene, with a sky image painted on each face. (Images are a lot easier and faster to render than 3D - objects, and just as good for far-distant scenery.) -
- -
- A skybox in the editor can be created using 2 different methods: -
    -
  • - Using a Cube Texture: create a skybox mesh and assign a cube texture to it. This method allows to use a custom texture for the skybox. -
    • -
  • - Using the Sky Material: create a skybox mesh and assign a new Sky Material to it. Babylon.js provides a material used to render sky that - is customizable so the sky can appear "alive". -
    • -
-
- -
Creating the Skybox mesh
- -
- To create a new skybox mesh, simply use the main toolbar Add {"->"} Skybox Mesh or right-click the scene graph and select{" "} - Add {"->"} Skybox Mesh. -
- -
- A Skybox mesh is a cube mesh set to have back faces visible, so it can be seen from the inside. By default, a Skybox will have no material assigned to - it. -
- -
- -
- -
Using Cube Texture
- -
- The goal here is to create a new material that will be assigned on the newly created Skybox. Then, assign an existing Cube Texture to the material as an{" "} - Environment Texture. The last step will be to edit the Cube Texture to use "Skybox" coordinates mode. -
- -
- -
- -
- To save loading time and performances in the application you are building, the editor provides a way to convert .hdr textures to .env{" "} - textures. The issue addressed with .env is the size and quality of IBL Environment Textures. -
- -
- More information about .env environement textures{" "} - - here - - . -
- -
- To convert a .hdr texture to .env, just right-click the .hdr file in the Assets Browser panel and select "Convert to .env". Once the Cube - Texture is converted, it will appear as a .env file in the assets and can now be used as an Environment Texture. -
- -
-
- -
- - - -
- -
-
- -
Using Sky Material
- -
- The principle here is the same as the previous method, but instead of creating a new material that will receive a Cube Texture, let's just create a new{" "} - Sky Material. -
- -
Once applied, the Sky Material can be edited on the fly to change the aspect of the Skybox.
- -
- -
-
- + + Introduction + +

+ A simulated sky can be added to a scene using a "skybox" (Wikipedia). A skybox is + a large standard cube surrounding the scene, with a sky image painted on each face. (Images are a lot easier and faster to render than 3D objects, and just as good + for far-distant scenery.) +

+ +
+

A skybox in the editor can be created using 2 different methods:

+ +
    +
  • + Using a Cube Texture: create a skybox mesh and assign a cube texture to it. This method allows to use a custom texture for the skybox. +
    • +
  • + Using the Sky Material: create a skybox mesh and assign a new Sky Material to it. Babylon.js provides a material used to render sky that is + customizable so the sky can appear "alive". +
    • +
+
+ + Creating the Skybox mesh + +

+ To create a new skybox mesh, simply use the main toolbar Add {"->"} Skybox Mesh or right-click the scene graph and select Add {"->"} Skybox Mesh. +

+ +

A Skybox mesh is a cube mesh set to have back faces visible, so it can be seen from the inside. By default, a Skybox will have no material assigned to it.

+ + + + Using Cube Texture + +

+ The goal here is to create a new material that will be assigned on the newly created Skybox. Then, assign an existing Cube Texture to the material as an{" "} + Environment Texture. The last step will be to edit the Cube Texture to use "Skybox" coordinates mode. +

+ + + +

+ To save loading time and performances in the application you are building, the editor provides a way to convert .hdr textures to .env textures. The + issue addressed with .env is the size and quality of IBL Environment Textures. +

+ +

+ More information about .env environment textures{" "} + here. +

+ +

+ To convert a .hdr texture to .env, just right-click the .hdr file in the Assets Browser panel and select Convert to .env. Once the Cube Texture is + converted, it will appear as a .env file in the assets and can now be used as an Environment Texture. +

+ +
+ + + + +
-
+ + Using Sky Material + +

+ The principle here is the same as the previous method, but instead of creating a new material that will receive a Cube Texture, let's just create a new{" "} + Sky Material. +

+ +

Once applied, the Sky Material can be edited on the fly to change the aspect of the Skybox.

+ + + ); } diff --git a/website/src/app/documentation/tips/shortcuts/page.tsx b/website/src/app/documentation/tips/shortcuts/page.tsx index 9d98416f2..b0314e05e 100644 --- a/website/src/app/documentation/tips/shortcuts/page.tsx +++ b/website/src/app/documentation/tips/shortcuts/page.tsx @@ -1,85 +1,73 @@ "use client"; -import { Fade } from "react-awesome-reveal"; - import { Kbd } from "@/components/ui/kbd"; -export default function DocumentationCreatingSkyboxPage() { - return ( -
-
- - -
Shortcuts
- - - - -
-
In Editor
- -
-
- ⌘Q or CTRL+Q: Quit application. -
-
- ⌘, (macOS only): Open editor's preferences. -
- -
+import { DocPage, DocHeading } from "../../components"; -
- ⌘C or CTRL+C: Copy selected text / selected object. -
-
- ⌘V or CTRL+V: Paste text / copied object. -
- -
- -
- ⌘S or CTRL+S: Save project. -
-
- ⌘G or CTRL+G: Generate project output (downsized & compressed textures, scripts map, output scene, assets copy, etc.). -
-
- ⌘P or CTRL+P: Open commands dialog. -
-
- ⌘F or CTRL+F: Focus selected object in preview panel. -
+export default function DocumentationShortcutsPage() { + return ( + + In Editor -
+
+
+
+ ⌘Q or CTRL+Q: Quit application. +
+
+ ⌘, (macOS only): Open editor's preferences. +
+
-
- ⌘T or CTRL+T: Select translation gizmo. -
-
- ⌘R or CTRL+R: Select rotation gizmo. -
-
- ⌘D or CTRL+D: Select scaling gizmo. -
+
+
+ ⌘C or CTRL+C: Copy selected text / selected object. +
+
+ ⌘V or CTRL+V: Paste text / copied object. +
+
-
+
+
+ ⌘S or CTRL+S: Save project. +
+
+ ⌘G or CTRL+G: Generate project output (downsized & compressed textures, scripts map, output scene, assets copy, etc.). +
+
+ ⌘P or CTRL+P: Open commands dialog. +
+
+ ⌘F or CTRL+F: Focus selected object in preview panel. +
+
-
- ⌘B or CTRL+B: Play / Stop scene in preview panel. -
+
+
+ ⌘T or CTRL+T: Select translation gizmo. +
+
+ ⌘R or CTRL+R: Select rotation gizmo. +
+
+ ⌘D or CTRL+D: Select scaling gizmo. +
+
-
+
+ ⌘B or CTRL+B: Play / Stop scene in preview panel. +
-
- ⌘M or CTRL+M: Minimize focused window. -
-
- ⌘W or CTRL+W: Close focused windows. -
-
+
+
+ ⌘M or CTRL+M: Minimize focused window. +
+
+ ⌘W or CTRL+W: Close focused windows.
- +
-
+ ); }