Since we launched the first version of the Decentraland SDK in April 2018, many projects have been using it to develop interactive content for Decentraland. Thanks to these early users from our community and partners, we’ve received lots of incredible feedback on how to expand and improve the SDK.

We identified that most people working with the SDK tend to belong to one of two groups: web developers or game developers. Some of the comments we heard showed that it’s challenging for both groups to work with the alpha API:

• “Applying a web approach to game design patterns is difficult even with web and game dev experience.”

• “Sufficiently complex games still require traditional game dev patterns or a cost-prohibitive amount of reinventing the wheel without tooling guidance. These patterns are outside of a web dev’s understanding and intuition.”

• “The React-ness is great for opening dev to a wider audience, but you’re still covering traditional developer bases.”

As you may know, we chose an approach inspired by React for the alpha. This was to help onboard web developers, who are usually more familiar with the React framework.

Although web developers were able to easily grasp the essential concepts of the SDK, we learned that it was difficult for them to adapt common game design patterns into the React paradigm. They often needed to reinvent practices that are otherwise well-known standards in traditional game engines, and this got harder and harder as projects grew in size.

All of this feedback has led to a new paradigm for the Decentraland API, based on an entity-component-system (ECS) architecture.

An ECS is a well known and proven game development pattern for writing code that’s high-performance by default. We want to help both web developers and game developers create better and more robust content for Decentraland, eliminating unnecessary complications and making the learning curve as smooth as possible.

Moving to an ECS will help us build graphical development tools, since an ECS architecture is a great foundation on which to build an editor. These tools, which we are working on now, will improve the experience of creating content, making the Decentraland platform more accessible for everyone.

As of today, the ECS will replace the old decentraland-api.

We’ve removed all the React-like code and built everything around the concept of entities. Everything in a scene is now an entity (e.g. NPCs, bullets, vehicles, etc.).

Every entity can hold several components which add characteristics or functionality to it. Therefore, the behavior of an entity can be changed at runtime by adding or removing components.

The information stored in components is changed over time by systems, these are what make scenes dynamic. Systems are able to execute functions periodically on every frame of the scene’s game loop, changing what’s being rendered.

For scenes that are made up of multiple parcels, we significantly increased the maximum amount of triangles and entities that are allowed. These limits used to be based on a diminishing curve function, now they are linearly proportional to the number of parcels. This means that you’ll be able to build a lot more on your estates!

By changing how the CLI is bundled, we’ve also managed to bring the size of the CLI down from 118 MB to only 12 MB!

Note: Support for Decentraland scenes written in XML format won’t be affected by the changes brought on by this version. The same XML syntax should remain valid. The only difference for XML scene builders is that they will also have higher maximum triangles and entities limits in multi-parcel scenes.

There are a number of changes that we’re excited to share with you! Below you’ll find the most noteworthy improvements, but be sure to check out our docs and release notes for all of the details.

One major difference introduced by the new SDK is that entity lifecycles are now written in an imperative style.

For example, now you explicitly tell the engine to add or remove an entity from the scene. The old SDK managed entity lifecycles in an implicit way. Instead of telling the engine to add a new entity, you’d just pass new render instructions that included an entity that wasn’t there before, and that would result in entities being created implicitly.

The new imperative style leads to code that’s a little more verbose, but much more intuitive, because it’s closer to how we think about what’s happening in the scene.

Scene states are no longer stored in a single state object. We’re taking away this layer of abstraction. Now the entities themselves embody the state of the scene.

This means that there’s no longer a setState() function- you can just change the values of entities and their components directly, which equates to changing the state. This will make your code a lot more straightforward.

The timing of code execution has also changed radically in this new version. Scenes used to be rendered only when a change in the state occurred, reactively.

Now, you can use a game loop that updates the scene about 30 times per second. We realized that not using game loops was confusing most of our developers with gaming backgrounds, since loops are standard practice for most traditional game engines.

So, forget about the setInterval() and setTimeout() functions for delaying the execution of code. Instead, timing is managed by the frames in the game loop. To delay execution, use a counter to count the number of frames or the total time elapsed.

To move an entity around your scene smoothly, the old API relied on transition settings that resembled CSS properties. Although this was an elegant solution for some use cases, it was another odd abstraction that took time to get used to.

Using transitions also had its setbacks, especially when it came to multiplayer scenes. The most uncomfortable aspect was that any movement between two points happened locally for each user, with no way to determine the intermediate positions of entities while they were moving. Paired with a bad frame rate or internet connection, this could lead to discrepancies between different users, ruining the experience in games.

The new API instead relies on making incremental changes to the actual position, rotation, or scale of an entity over each frame of the game loop. This is another standard practice in traditional games. It makes more sense for a 3D environment where the intermediate position of an object along a path can be critical to a game’s logic.

We’ve talked about some of the biggest changes introduced in the new SDK, but there are still lots of smaller updates, fixes, and improvements.

• The main scene code is no longer an object with methods, but rather a straightforward script. Now you don’t need a

  sceneDidMount() method. If you want something to be executed when the scene is loaded, simply write loose code into the .ts file and the lines in the script will be called in order.

• We no longer use a

  render() function in the scene’s code. Rendering is now handled in the backend by the engine. You don’t have to explicitly tell the engine when (or what) to render. The when simply follows the frames of the game loop. The what consists of every entity that’s been added to the engine.

• Entities no longer have different types. Now all entities are generic and their characteristics are determined by the components they own. For example, there are no

  box or

  plane entities, instead you create a generic entity and add a

  BoxShape or

  PlaneShape component to it.

• Individual entities no longer need to have ids or keys to be properly distinguished by the engine.

• The main scene file is now a

  .ts instead of

  .tsx, as no XML-like syntax needs to be declared.

• It’s no longer necessary to import the

  Decentraland API library into the main file. All base libraries are implicitly imported into the

  .ts file now, making it simpler to get started.

• The ECS uses Quaternion angles instead of Euler angles to store rotations. This makes our SDK more robust and helps our compatibility with other frameworks. Thankfully, the SDK includes a number of handy helpers that allow you to provide values expressed as Euler angles, which are a lot easier to use.

These are just a few of the main differences introduced by the new ECS version of the Decentraland SDK.

To show how this looks in a concrete example, we’ll be sharing a tutorial specific to the new SDK tomorrow, or start today by taking a look around the scene examples doc!

If you want to dig deeper into the new ECS, head over to our documentation!