Runtime Version 2 Upgrade Guide

Technical Support
1

Runtime Version 2 Upgrade Guide

Studio is making a big leap forward in physics simulation! Under the hood, we’ve upgraded to a new and improved physics engine, and this change brings a more modern foundation to power your projects. In this post, we will guide you through the steps for upgrading to 2.0.

Please report any issues you encounter while upgrading by replying to this post or via Discord on the #community-help channel.

:white_check_mark: Installing

In your project’s Settings panel, under the Project Version header, upgrade your Runtime version to 2.0 or later.

You will need to select Build (or press cmd-save) to initially adopt the new runtime. Please note that there are breaking API changes, as well as changes to the underlying physics calculations for properties like friction, restitution, and damping. See the next sections in this guide for details.

Note: You can always migrate back to Runtime Version 1.X to keep existing behaviors as-is.

:magnifying_glass_tilted_left: Updates to the API in 2.0

Updates to ecs.Collider

rollingFriction and spinningFriction are no longer supported properties in 2.0’s Collider component. We recommended using the general friction property, as well as linearDamping and angularDamping to control rolling behavior and speed.

We added a new type property (required) to ecs.Collider to allow for controlling if and how physics simulation should apply overall. Previously, a mass value above 0 determined if a collider was dynamic or not (0 mass = Static), and Kinematic colliders were not supported.

  • Allowed values: ColliderType.Static, ColliderType.Kinematic, ColliderType.Dynamic

  • Kinematic colliders are not affected by physics forces, but can have motion and can affect other dynamic bodies through collisions

  • Type is now a required property

  • See Collider API documentation for details and use cases

Example ecs.Collider.set before and after 2.0

// Before

ecs.Collider.set(world, component.eid, {

  shape: ecs.ColliderShape.Sphere,

  radius: 1,

  mass: 0,

  eventOnly: false,

  gravityFactor: 1,

  lockXAxis: false,

  lockYAxis: false,

  lockZAxis: false,

  friction: 0.5,

  restitution: 0,

  linearDamping: 0,

  angularDamping: 0,

  spinningFriction: 0,

  rollingFriction: 0

})

// After

ecs.Collider.set(world, component.eid, {

  shape: ecs.ColliderShape.Sphere,

  type: ecs.ColliderType.Static,

  radius: 1,

  mass: 0,

  eventOnly: false,

  gravityFactor: 1,

  lockXAxis: false,

  lockYAxis: false,

  lockZAxis: false,
 
  friction: 0.5,

  restitution: 0,

  linearDamping: 0,

  angularDamping: 0

})

Updates to world.Three

Changed matrix update mode: manual by default, which is more optimized. If modifying three.js objects directly, calling world.three.notifyChanged() is required on each changed object, or go back to the original behavior with world.three.setMatrixUpdateMode(‘auto’)

Typescript Updates

Enabled stricter typescript checking on by default at build time to improve error reporting.

:magnifying_glass_tilted_left: Updated Physics Behaviors in 2.0

In 2.0, some of the new Physics engine’s underlying calculations differ. Test key interactions in your scenes. Focus testing on friction, bouncing, and high-speed collisions. You may need to fine-tune your physics settings to achieve the desired feel.

Key Updates to Physics Behaviors

  • Friction: Behavior may differ and sliding objects may feel looser depending on your setup. Note: you may need to adjust linear or angular damping values in 2.0 to achieve the right friction, and rolling and spinning friction are no longer supported.

  • Restitution/Bounce: May resolve with different energy, and objects may have more bounciness overall right after migrating.

  • Damping (Angular and Linear): May resolve with different speed, and objects may have more speed overall right after migrating.

  • Collision Detection: Fast-moving objects may now interact differently (less tunneling). Re-test projectiles or physics-driven animations.

  • Update speed overall: Physics may update faster, which can reveal timing differences if you have logic tightly coupled to physics steps.

:handshake: Wrapping Up

This upgrade is all about giving you a stronger, faster, and more reliable physics engine while keeping your workflow unchanged.

We’re here to help. Share any issues you encounter with us on as a reply to this post, or on Discord on the #community-help channel. This is a big upgrade, and we want to know how it’s working for you.

We can’t wait to see what you build with this new physics foundation!

2 Likes
2

Thank you for sharing this, it is extremely helpful.

1 Like