Guide to make modifications in the Decentraland Unity plugin

Español

Why do I need to modify the Unity plugin?

Using the Decentraland SDK to place entities "manually" in the typescript code may be a slow and tedious process, especially if you have to put a lot of them and you have to look one by one if they are in the right place.

That's why you have tools to help you build a scene, like the Decentraland builder or the Unity to DCL export plugin. However there are a limited set of things you can do with them.

In this guide we'll see how to make custom modifications to the Unity plugin for DCL to expand the number of things you can export to code from the Unity scene editor.
​
Before starting with this guide you should have a minimun knowledge of the Decentraland SDK, the basics of how to export a scene from unity to DCL and some programing basics (we'll use typescript and C#).

Decentraland Documentation

https://docs.decentraland.org/development-guide/coding-scenes/

https://docs.decentraland.org/blockchain-integration/display-a-certified-nft/

The Mission

---

We'll do an example modification of the plugin to make it export to typescript the necessary data to place an NFT in the scene.
Taking this example as base, you should be able to make your own custom modifications to meet your project needs.

Resources

---

• Unity version 2018.3.6f1
• Visual Studio (recomended to use with unity)
• Decentraland SDK
• Unity to DCL export plugin
• Decentraland for starters guide

Prepare your Typescript project

---

First of all, we are going to code our custom component and have it ready to use in the typescript project.

https://docs.decentraland.org/development-guide/entities-components/#custom-components

It isn't necessary to make a custom component to place an NFTShape (which is already a component), but for the sake of the guide we'll do it anyway, besides it will be useful for you as a base to make your own more complex components.

Before start writing code in your game.ts file, be aware that the Unity export plugin will ovewrite the entire game.ts file and your code will be lost, because of this we need to work in a separate file.
​
Create a new file src/imports/components/NFT.ts with the following code:

//Creates an NFTShape component with the given info
export function createNFTComponent(entity: IEntity, smartContract: string, tokenId: string){
entity.addComponent(
new NFTShape('ethereum://'+smartContract+'/'+tokenId,Color3.Blue())
)
}
//Add a NFTdata component to the entity, creates an NFT component with the given info
@Component('NFTdata')
export class NFTdata{
entity: IEntity //entity of the NFT
smartContract: string //Smart contract of the NFT
tokenId: string //Token ID of the NFT
constructor(entity: IEntity, smartContract: string, tokenId: string){
this.entity = entity
this.smartContract = smartContract
this.tokenId = tokenId
createNFTComponent(entity, smartContract, tokenId)
}
}

And another one src/imports/index.ts with:

export { NFTdata, createNFTComponent } from "./components/NFT"

Now we have our code ready for when our modified plugin exports the game.ts

Make a Unity script to hold the data to export

---

Create a empty script in Unity and open it in visual studio (or your favorite code editor).

You only need to store here the NFT address info for this guide, but fell free to add anything you need for your project.

public class nft_script : MonoBehaviour
{
public string smartContract;
public string tokenId;
}

Add this script to the entity in the scene you want to have the NFT as component and fill the address data.
​

Address: 0x06012c8cf97BEaD5deAe237070F9587f8E7A266d
Token id:
​558536

Now we have the data stored in our entity, the only step left is to modify the plugin to translate this data to our project in typescript.

Modify the Unity plugin in C#

---

Modifing the plugin may seem like an overwhelming task, but keep in mind we only need to add our little pieces of code in it and expand its functionalities, simple if you know where to do it.
​
Open SceneTraverser.cs in the Decentraland plugin folder: Assets/Decentraland/SceneTraverser.cs
​
Find the public static ResourceRecorder TraverseAllScene function and add the following code after the comment //====== Start Traversing ======

//====== Start Traversing ======
if (exportStr != null)
{
exportStr.AppendLine("import { NFTdata } from \"./imports/index\"\n\n");
}

This will import our NFTdata class at the start of game.ts
​

Next find the public static void RecursivelyTraverseTransform function and after exportStr.AppendFormat(NewEntityWithName, entityName, tra.name); add this code:

nft_script nftObject = (tra.gameObject.GetComponent("nft_script") as nft_script);
if (nftObject)
{
exportStr.AppendFormat(SetNFT, entityName, nftObject.smartContract, nftObject.tokenId);
}

Last step, find the place where the export strings are declared and add the SetNFT string at the end.

private const string SetNFT = "{0}.addComponent(new NFTdata({0}, \"{1}\", \"{2}\")) \n";

This code will check if the exported entity has an nft_script and will add the NFT data component to the entity in our game.ts file.

With all done your scene is ready to be exported to a typescript project and your resulting game.ts should look like this:

import { NFTdata } from "./imports/index"

var entity1372n = new Entity("NFTentity")
entity1372n.addComponent(new NFTdata(entity1372n, "0x06012c8cf97BEaD5deAe237070F9587f8E7A266d", "558536"))
engine.addEntity(entity1372n)
entity1372n.addComponent(new Transform({ position: new Vector3(6, 1.5, 6) }))
entity1372n.getComponent(Transform).rotation.set(0, 0, 0, 1)
entity1372n.getComponent(Transform).scale.set(1, 1, 1)

Final tips

---

You can access from anywhere in the project to an array of entities with your custom components, this can be usefull to control where and how some components or behaviours start.

engine.getEntitiesWithComponent(NFTdata)

You don't need to make complex new components if you don't have to, for example you can export from unity only the info to put an entity in an array and apply to them a custom behaviour.

Before start making your componets, take a look at the decentraland sdk and the decentraland utils library, they may have what you are looking for.

ECS API Reference:

https://github.com/decentraland/ecs-reference

decentraland-ecs-utils:

https://github.com/decentraland/decentraland-ecs-utils

npm install decentraland-ecs-utils

Conclusion

---

If you have understood the steps done in this guide, you are ready now to make your own components for decentraland and place them using the Unity editor, this will be very usefull to fill your scenes with gameplay and interaction. I hope it makes your development process for decentraland easier.

---

Alex Picazo

PROGRAMMER

Videogame programmer, love developing cool stuff. Always searching for new interesting stories.

LinkedIn