This new SDK release focuses on the creator’s experience, and removes a number of pain points that SDK users have been struggling with for a while. There’s still a long way to go in that regard, and a very long list of ideas that will be tackled next, but hopefully this release will start making the experience of content creation a lot more joyful.

As the new version number neared, there was an acknowledgement that the release had to be something special for content creators, and it was also time to rebuild several things from the ground up. Check out what’s new and how to take advantage of the changes…

How to update

You should run both these installations:

Update your CLI version globally, by running this anywhere:

Update the dependencies on each of your scene projects, by running this in the scene folder:

As of now, the CLI and SDK will both check when you attempt to run a scene to make sure you’re using compatible versions of each, to make sure you’re never stuck trying to run a scene that uses the new SDK with an old CLI or vice-versa.

TIP: If for some reason you want to combine versions of the CLI and the SDK that weren’t released together, you can run dcl start --skip-version-checks.

The new Preview

The biggest changes in this release take place in the scene preview. The preview was reengineered heavily, so that it now shares a lot more of the actual code used in production when you enter Since the preview is meant to anticipate what it will be like for players in your scene, the closer content creators have to that, the better.

The first thing you might notice when you open a scene preview is the full Decentraland UI on-screen. This includes the map, the chat, the bar at the bottom, the backpack… everything players see in-world is there. This is of course useful when you’re positioning your own UI elements to make sure they don’t get covered by other parts of the UI. But it also provides an easy way to switch to night mode, or to change any of the settings like turning off ambient occlusion or trying your scene in high or low resolution settings, turning sounds off, or even changing your avatar wearables. Thanks to this, you can make sure your scene looks good in any scenario. Changing your wearables also makes it so much easier to debug scenes that react to what wearables players have on.

Another thing you’ll notice is that the surrounding plots of land are no longer an empty grid, but instead show the default empty parcel content, with some random trees and bushes. This gets things a little closer to the real deal, with part of the browser’s memory busy rendering those other scenes, just like it’ll be when your scene is live. It also helps you see the exact height of the default ground level around your scene, allowing you to fine tune your ground to that.

If you jump to the third person view, you’ll also notice that your avatar is no longer the same default avatar, but instead a randomly generated one that changes every time you reload. If you’d prefer to keep consistency across your sessions, you can store an avatar profile by adding a PLAYER parameter to the URL and assigning it any string value. When using this, the preview will store your avatar’s settings locally on your browser, to retrieve them whenever you use the same string on the PLAYER parameter. For example, every time you open the preview with the URL, you’ll have the same avatar.

You can also connect to the preview with MetaMask and load the scene using your actual avatar, then switch your wearables to anything that the account owns. SDK veterans will be familiar with the trick of manually adding &ENABLE_WEB3 to the preview URL to connect to MetaMask. With the newest CLI version that’s no longer necessary. You can run dcl start --web3 and launch the preview connected to MetaMask right away.

Fully sandboxed code

Even though never documented or encouraged, older versions of the SDK had access to some browser-native functionality, like the setTimeout function. The tricky thing is that, although Decentraland today runs always in the context of a browser, that won’t always be the case. So in the future, when the Decentraland native desktop version exists for example, browser resources won’t be there and scenes that make direct use of the browser won’t be able to load in that context.

This unholy release number was the perfect time to start preventing the use of those browser functionalities in preview. Note that scenes built with older SDK versions can still get away with using these browser resources, so existing content won’t break.

Tip: If you can’t live without the setTimeout function, check out the setTimeout function in the Decentraland Utils library. It behaves just like the function you know and love, but is built entirely on the Decentraland ECS.

Better debugging

Debugging is getting better and better. Older releases of the SDK already featured detailed error messages on the command line console when the scene was compiled, indicating the file and line with the offending code. Error messages on the browser console are now getting a lot more useful, including links to the .ts file & line, that you can read in the “sources” tab of the browser.

This is extremely useful, because it doesn’t just show you where the bug is, once you’re in the sources tab you can even add breakpoints dynamically in your scene, and play around with pausing your code.

Debugging best practices probably merits a whole video tutorial, which should be coming soon.

This full source code of the scene is available in the “sources” tab of the browser when you build your scene locally and preview it. When you deploy your scene, the scene is rebuilt without including it, to make sure your source code isn’t anywhere to be found in Decentraland’s servers, and can’t be easily copied or exploited.

This also comes with an added bonus: since running dcl deploy now runs a build of your scene before deploying, a typical error seen countless times in the past has been prevented. Suppose you change one minor thing like an outbound link or a UI text, and then deploy your scene without previewing it first – the changes aren’t uploaded, because the compiled scene was never built with those last changes. As of now, that shouldn’t happen, because deploying also rebuilds the scene.

Other fixes

There are a number of other fixes that have been implemented with this release:

  • When hot reloading unexpected things would often occur and you would have to manually reload to see the scene properly rendered. Although some corner cases still need to be fixed, the reliability of hot reloading has taken a huge leap forward
  • Several people have had problems installing the Decentraland utils libraries in their scenes and have had to manually configure things in the tsconfig.json file to make them work. Now with the latest CLI version, that should no longer happen. Installing any of the utils libraries should work smoothly
  • When having an entity attached to the player avatar, fast movements would often result in some slight lags in the position of the object relative to the camera. This is now fixed in all scenes, regardless of SDK version, but you’ll see it fixed in preview as of version 6.6.6
  • When triggering emotes on a player, the PredefinedEmote enum now has access to a few new emotes like HAMMER, SHRUG or HEAD_EXPLODE
  • The Teleport confirmation UI window now works in preview
  • When resizing the browser window, any UI elements that had their position or size set relative to the canvas now readjust to the new window size
  • When hiding avatars with an avatar modifier area, the hiding of avatars now works well in preview

Shiny new repo

Much of Decentraland’s core code used to live in a single large monorepo, that’s now been migrated into several separate repos.

The SDK itself now lives in its own brand new repository here:

Also, if you want to report any issues with the SDK, please add an issue to this repository, describing the issue in as much detail as you can:

All of Decentraland’s repositories are open source, and contributions from the community are encouraged, so if you feel like there’s something you wish was possible with the SDK, feel free to make a pull request to the js-sdk-toolchain repo.

As always, if you have any questions or issues (or just want to throw in a few horn emojis), feel free to reach out to the Foundation team on Discord. Enjoy the updates!