Premise
🎓 This guide will take you through the Decentraland Exporter Toolkit, in order to learn how each part of the toolkit works and have a clear vision about what can we do from the Unity editor.
The mission
🎓 Create an user guide to explain the usage of the **Decentraland Exporter Toolkit for every new user that wants to create scenes in Dcl from Unity.
⚙️ Resources
- Unity 2022.3.12f1 - https://unity3d.com/es/get-unity/download/archive
- Unity Hub https://unity.com/download
Unity Editor
First of all we need to install the Unity Editor. We highly recommend installing the Unity Hub as well to simplify the process. After installing Unity Hub, let’s head to the Unity Archive and look for the Unity 2022.3.12 version click on “Unity Hub” button to install the Editor.
In Unity Hub, click on New Project, this will open a window with different templates, select the 3D Core option and click on Create Project.
To install URP via package manager go to Window → Package Manager
Change the Packages in top left to Unity Registry and look for the Universal RP package to install it.
📦 Unity Package
You will need to download and install the Unity Package with the Exporter Toolkit. You can find the latest version in this Github repository. Double click the package to import it to your Unity project.
☀️ URP Configuration
Go to the Project Settings, you can find it in Edit → Project Settings top left of your screen. Now, in the Graphics tab, set-up the URP Asset that comes in the Exporter ToolKit package. Open the Scriptable Render Pipeline Settings tab by clicking on the circle icon on the right and select the URP Asset.
🛠️ Dcl Exporter ToolKit
Now that everything is set-up, let’s open the Exporter. You can find it in the Dcl Exporter ToolKit tab, top of your screen. Open the Control Panel option to get started.
The first time opening the exporter, this window will show all the dependencies needed to use the exporter.
In this editor window, you can manage the dependencies with a simple 4-step guide to initialize your project. You can't proceed further in the tool without installing the dependencies and clicking the "Check Dependencies" button. This will execute a cmd command to check if Node.js and the npm packages are installed on your computer.
Below the Dependencies you can find a **Create New Project** button, this will set-up our Dcl project route and files. Click it and select an empty folder inside your Unity project.
Now go to the Exporter tab of the Control Panel, in this interface you will be able to Export and Run your Dcl projects. For now, to make sure everything is working properly, click on the Run Local option down below. This will open a tab in your browser to run a local test of your Dcl Project.
If everything is correct, you will spawn in an empty Dcl scene that looks like this:
Now that we have succesfully created our first Dcl project from scratch, let’s go back to the Exporter’s interface and have a more in depth look into each tab so we can start developing our Dcl scene.
🖥️ Config
🔗 Dependencies
Back in the Config tab, below the Dependencies’ installers we previously used, we can find the Dependencies Version Control.
This is a small box that displays all the installed dependencies versions and contains 2 buttons to check if there are new dependencies versions installed or clear the dependencies information if you want to go back to the previous window to manage dependencies.
📁 Project Setup
Here we can create a new Dcl project from scratch in an empty folder (as we have previously done), locate an already existing project manually, or use the Autofind feature, which will show all available projects to choose one from.
🖥️ Manager
📄 Scene Metadata
Here you can set up all the Dcl metadata needed including Land Name, Description, Spawn Points, etc.
The Open Parcel Editor button at the top open a new window where you can configure the parcels for your Dcl Scene.
In this window, you can:
-
Create regular parcels with a fixed size.
-
Create a custom parcel drawing in a grid starting from the base parcel at the bottom left corner.
-
Edit the parcel list manually.
This parcel creation form must maintain the following structure:
"[X],[Y]
[X],[Y]
[X],[Y]"
The first parcel will be the base, located at the bottom left corner of the scene.
-
Obtain the Dcl parcels from the marketplace, using the link or just the token ID of a decentraland estate.
🛡️ Special Permissions
Depending on your gameplay configurations you may need to enable certain special permissions:- Enable voice chat: allows users to use voice chat in the scene
- Enable Portable Experiences: enables the use of smart wearables
🏗️ Builder
📊 Statistics
In the next part we have one of the main features of the exporter, it shows info about the current scene like the number of triangles, objects, entities, materials, etc. It shows the recomended limit of each resource based on your parcel size to have an optimized scene and avoid exceeding the limits of Decentraland.To update this info we need to Refresh the scene by clicking the button or selecting a time interval to auto refresh the scene. Refreshing the scene for the first time will create a GameObject called .dclManager that will be ignored during the Export, It contains info and the scene metadata to be exported.
In this part we can also set the bounding boxes from every mesh with a dcl object and debug bounding box active. This will be useful to make sure every bounding box is within our parcel’s boundaries.
☀️ Decentraland Skybox & Illumination
In this section we can manage the Dcl Skybox to preview the illumination and reflection probe at different daytimes, This is a helpfull tool to save time checking the illumination in unity before exporting to Decentraland.
00h Skybox Illumination
04h Skybox Illumination
08h Skybox Illumination
12h Skybox Illumination
16h Skybox Illumination
20h Skybox Illumination
🪄 Exporter
🔗 CLI
Decentraland CLI UI
In this section we can Initialice a new Dcl project, Update the Decentraland CLI in our computer or Update the SDK in the selected project.
📝 Export Options
In this section of the exporter window, we will find the main feature of the ToolKit, which is the Export option. This option translates our Unity scene into code written in the index.ts file, which is the script used to build Dcl scenes. Every time we export, the index.ts file is deleted and rewritten, so keep this in mind if you are manually editing parts of the index.ts.
There is secondary export options, which execute “partial” exports depending on the current needs of your scene, we will see use cases later on.
Before you export you can also select the type of GLB you want to export.
📁 Decentraland Project
Decentraland Project folder UI
In this section, we can manage the Dcl project folder. We can open the root folder, open specific scripts like scene.json with the metadata, index.ts where the main code is exported, or the package.json script.
We can also run a Dcl scene locally to test our exports by executing a cmd command from Unity.
🧊 Box, Plane, Sphere and Cylinder
You can spawn primitive objects that won’t be exported as GLTF meshes but as Decentraland primitives. You can spawn this objects by right click in the Hyerarchy or directly accessing the GameObject tab in the Unity toolbar.
You can create custom Areas that will create Triggers or Modifier Areas in Decentraland, You can use this areas as inputs for Animation, Teleports, etc.
Spawn this areas just like the primitives before, in the GameObject Unity menu.
This is how the default Trigger Area looks like:
- Trigger: Trigger areas have 2 configurable lists of events for enter and exit events
- Modifier: This areas are specific from Decentraland and let you control the player camera and hide avatars or passports from players inside the area.
You can create custom materials for your objects. To make a new material go to Assets → Create → Material.
🪄 Material properties
There are multiple properties we can customize for the material, the basic ones are:
- Base Map: changes the color of the object
- Metallic Map: this will change how “metallic” your object looks, by increasing or decreasing the amount of influence the skybox has over the tint of the object’s reflections.
- Smoothness: amount of reflectiveness the object has. More smoothness, more reflectiveness.
- Normal Map: controls how the object’s surface reacts to lighting.
- Emission: adds a “glowing” effect to the object
Here’s some examples of different materials with different properties:
Example 1: 0.5 Metallic / 0.5 Smoothness
Example 2: 1 Metallic / 1 Smoothness
Example 3: 0 Metallic / 0 Smoothness
Example 4: 0.5 Metallic / 0.5 Smoothness / Yellow Emissive
You can use a custom texture image for each of the properties when working with non-primitive assets. Later we will see a practical example of this in a video tutorial.
You can find all the aviable components when clicking Add Component in any gameObject and search for the submenu Dcl Exporter ToolKit.
⚙ DclObject.cs
This component is the base of the exporter, clasify every entity in diferent types like Dcl Primitives, GLTF, Text Shapes, NFTs and more. This different DclObjects will have a different behaviour when exporting the solution.
The component is needed if you want that gameObject to appear in the game.ts script.
DclObject can modify collisions from here for Dcl primitives and will show the gameObject name for the Decentraland export.
The checkbox Debug Bounds will draw the bounding box of a mesh when selected or activated in the statistics section. By clicking in ignore object, This DclObject won’t be exported and this object will be ignored during the export.
⚙ AnimatorDcl.cs
The AnimatorDcl is an alternative to the Unity Animator with the clips that will be exported into a Decentraland Animator.
The default Animation will be the animation playing if we set the Start Playing checkbox to true.
Each clip have a few parameters to control if the clip should loop and the animation speed.
🎶 AudioSourceDcl.cs
With this component you willl create a Decentraland AudioSource on this entity, You can set a default clip with params and a list of clips to activate through input events or however you want.
📽️ Stream Video
This component gives you the ability to export a streaming video screen, should be attached to a primitive plane as screen but you can use other Decentraland primitives.
Set the video URL that can also be a relative path to a video in the decentraland project folder and this video will be playing in the screen.
🖼️ Stream Image
This is similar to the Stream Video component but getting an image from the URL instead of a video.
🎓 Force GLTF - Force_GLTF.cs
This component will ignore the dcl object type and will force to export the object as GLTF.
Can be used for example to combine multiple meshes in a single one with an empty parent and this component.
🎓 Break Child - Break_Child.cs
This component will export the object as a single GLTF. It's used for child objects that you want to export as individuals.
🎓 GLB Placeholder - glbPlaceholder.cs
With this component, you can set a path and the exporter will create a GLTF shape with the model in the selected path. It works very similarly to the Stream Image/Video components. Keep in mind, your GLTF shape will inherit the placeholder’s transformations.
🎓 Late Loader - lateLoadMesh_script.cs
This will force the mesh to be written in the last part of the index.ts
🎓 Prefab Overwritter - ovewriteMesh_script.cs
Prefabs are exported as a single mesh to instanciate over the scene multiple times, if you want any specific prefab to export as a normal GLTF you can add this component.
🪟 BillboardDcl.cs
Adding this component to any gameObject will make it face the player camera in Dcl, you have options to fix the rotation around an axis to do different types of billboards.
🖱️ InputEventDcl.cs
With this component you will be able to create pointer input events to play animations, teleports, open links, etc.
You can create a list of events that will be executed in an event when pressing the button selected while aiming to a gameobject.
You can switch between pointer down and pointer up, set the hover text and the distance to interact. and Select the input button in a list with multiple options.