Skip to content

Latest commit

 

History

History
158 lines (105 loc) · 12.5 KB

v1.7_to_v1.8.md

File metadata and controls

158 lines (105 loc) · 12.5 KB

How to upgrade from TDW v1.7 to TDW v1.8

Read the changelog

Read this for a complete list of changes.

Known bugs

Bug: Can't create a Linux build without deleting some Flex shader files

(This is relevant only to users who have access to the C# source code in the private TDWBase repo.)

To create a Linux build, delete all Flex shaders located in TDWBase/Assets/NVIDIA/Flex/Resources/Shaders that have DrawParticles or Fluid in their name. Otherwise, the Editor will crash to desktop. This is handled automatically when we build and upload TDW releases to GitHub.

Update: Fixed as of March 7, 2021, having upgraded to Unity 2020.2.7

Bug: Can't draw Flex particles on Linux

It's currently not possible to draw Flex particles ("draw_particles" in the Command API) in Linux. Attempting to create a build with the Flex particle shaders for Linux results in a crash-to-desktop. This is new as of Unity 2020.2.2 and it is likely that a future Unity Engine upgrade (i.e. to Unity 2020.2.x) will fix it. As a matter of course, we apply minor Unity Engine updates to TDW whenever they're available. Should one of these updates fix this particular issue, we'll note it in the changelog.

Update: This has probably been fixed (see update note from March 7 in the above section). However, we don't have Ubuntu 16 test machines and haven't been able to test Flex on Linux.

Renamed some streamed scenes

We updated the asset bundles of some streamed scenes to make them compatible with Unity 2020.2; we didn't introduce any changes that would affect the scenes at runtime.

tdw_room_2018 has been renamed tdw_room and archviz_house_2018 been renamed archviz_house. If your controller references either scene, you need to change the scene name accordingly.

Graphics improvements

There was a persistent bug in TDW that caused certain models and materials to not cast shadows or reflect light correctly. This has been fixed.

We strongly recommend using the rendering as-is because rendering is superior to previous versions of TDW without affecting performance. If your project was made in a pre-v1.8 version of TDW and it's absolutely required that the rendering stay the same, you can send this command:

{"$type": "set_legacy_shaders", "value": True}

Additionally, the post-process vignette affect is now disabled by default. To re-enable it:

{"$type": "set_vingette", "enabled": True}

Fixed the _depth, _depth_simple, and _normals passes

The fixes to the _depth and _depth_simple passes were introduced in the last few v1.7 releases, but they're worth mentioning here: the depth data is now far more accurate. It's also a different format. All other passes are .jpg or .png byte arrays. The _depth and _depth_simple passes are raw RGB numpy arrays because we found that encoding to png resulted in a loss of information. This means that depth images need to be encoded to png before being saved to disk. This is handled automatically by TDWUtils.save_images() but if you've been saving images with your own code, you might need to review the code within TDWUtils.save_images() to see how to save a depth image.

Additionally, we found that the _normals pass was inaccurate for similar underlying reasons. This has been fixed as of TDW v1.8.0 (not v1.7). The _normals pass is still encoded as a .png file, so you won't have to change any of your code to write it to disk.

Compiling a build takes much more time

(This is relevant only to users who have access to the C# source code in the private TDWBase repo.)

Creating a build in Unity Editor can take much more time than in previous versions of TDW. This is because Unity needs to compile a lot of missing shaders in order to fix long-standing graphics issues (see above). Creating a build can take 10-15 minutes. While we're still understanding this process, it seems that Unity Editor will cache some of the shader data, meaning that the next time you create a build, it will be much faster. Upgrading Unity Engine will likely clear this cache, as will "Reimport All".

Linux and OS X builds now have execute permissions

By default, all Linux and OS X builds will have execute permissions correctly set. In order to preserve this, the builds are now stored as .tar.gz instead of .zip

Removed commands

Removed toggle_image_sensor. You should use enable_image_sensor instead.

Asset Bundle Creator

If you've used the Asset Bundle Creator in TDW v1.7 or prior, delete the directory. The next time you use the Asset Bundle Creator, it will recreate the directory and Unity project.

Deprecated the Sticky Mitten Avatar and added the Magnebot

The Sticky Mitten Avatar has been deprecated, meaning that we don't plan to continuously improve the Sticky Mitten Avatar unless a specific ongoing project needs support.

The Sticky Mitten Avatar has been replaced with the Magnebot which has a new high-level API. The Magnebot retains most of the same functionality as the Sticky Mitten Avatar but far less buggy. We strongly recommend any new projects that want to use TDW for quasi-robotics experiments to use the Magnebot, and we encourage anyone still using the Sticky Mitten Avatar to upgrade to the Magnebot if possible.

Key differences

  • The Magnebot uses Unity's new ArticulationBody component instead of the old HingeJoint component used by the Sticky Mitten Avatar. HingeJoints tend to stretch or glitch; ArticulationBodies don't have these problems.
  • The Magnebot is a robot, not an avatar. It won't respond to avatar commands such as turn_avatar_by and it doesn't initialize with a camera. See this document for more information.
  • The Sticky Mitten Avatar responds to both physics and non-physics commands. The Magnebot responds only to certain physics commands.
  • The Sticky Mitten Avatar moves around the scene by having forces continuously applied to it. The Magnebot has wheels (which in the API are just revolute joints without angle limits) that turn to move it forward.
  • Magnebot has a somewhat difference shape and size than the Sticky Mitten Avatar.
  • There are two variants of the Sticky Mitten Avatar: "A_StickyMitten_Adult" and "A_StickyMitten_Baby". There is only one Magnebot. However, the Magnebot can slide its torso up and down. You can constrain the height of the torso to be similar to either of the Sticky Mitten Avatars.
  • The Sticky Mitten Avatar can pick up objects nearby a mitten (pick_up_proximity) or adjacent to a mitten (pick_up). The Magnebot only picks up objects adjacent to the magnet.
  • When using a Sticky Mitten Avatar, the controller must continuously send pick_up or pick_up_proximity until the output data indicates that the object has been picked up. When using a Magnebot, the controller needs to send set_magnet_targets, after which the Magnebot will pick up any of those targets on the frame that the magnet collides with them.
  • A Sticky Mitten Avatar picks up objects by attaching a breakable FixedJoint component. A Magnebot picks up objects by temporarily destroying the object's rigidbody and "fusing" it to the magnet. This means:
    • The link between a magnet and the object is unbreakable (and will never glitch) until the object is dropped.
    • Rigidbody commands such as set_mass can't be sent to objects held by a magnet.
    • send_rigidbodies will return default data for held objects.

API Comparison

Creation and Destruction

Sticky Mitten Avatar Magnebot
create_avatar add_magnebot
teleport_avatar_to teleport_robot
destroy_avatar destroy_robot

Movement

Sticky Mitten Avatar Magnebot
move_avatar_forward_by set_revolute_target

Set target angles for the Magnebot's wheels.
set_avatar_drag set_immovable
set_avatar_rigidbody_constraints set_immovable
turn_avatar_by set_revolute_target

Set target angles for the Magnebot's wheels.

Arm Articulation

Sticky Mitten Avatar Magnebot
bend_arm_joint_by set_revolute_target
set_spherical_target

Add or subtract from the current angles. See: Robot.get_joint_angles().
bend_arm_joint_to set_revolute_target
set_spherical_target
pick_up set_magnet_targets
put_down detach_from_magnet
rotate_waist set_revolute_target

Set a target angle for the Magnebot's column. Unlike the Sticky Mitten Avatar, this is a physics motion.
stop_arm_joint set_revolute_target
set_spherical_target

Set the targets to the current angles. See: Robot.get_joint_angles().

Output Data

Sticky Mitten Avatar Magnebot
send_avatars send_robots
send_magnebots
send_avatar_segmentation_colors send_static_robots

Static Parameters

Sticky Mitten Avatar Magnebot
adjust_joint_damper_by
adjust_joint_force_by
set_joint_damper
set_joint_force		 set_robot_joint_drive

Get the default joint drive parameters via send_static_robots.
set_avatar_mass set_robot_joint_mass

Set the mass of the root object. See: StaticRobot.get_is_root().
set_sticky_mitten_profile set_robot_joint_drive
set_robot_joint_mass
set_avatar_physic_material set_robot_joint_physic_material

Unique to the Magnebot

Command Notes
parent_avatar_to_robot Read this.
set_prismatic_target The torso of the Magnebot can slide up or down.

Unique to the Sticky Mitten Avatar

Listed here are Sticky Mitten Avatar commands specific to the Sticky Mitten Avatar, as opposed to avatars in general.

All commands normally used for a kinematic avatar (such as image capture commands) are applicable to an avatar parented to a Magnebot via the command parent_avatar_to_robot.

Command Notes
adjust_joint_angular_drag_by
set_joint_angular_drag		 ArticulationBody doesn't have an angular drag parameter.
apply_force_to_avatar The Magnebot can't move laterally because it uses wheels to move.
enable_avatar_transparency
pick_up_proximity Magnets only "pick up" objects that they collide with.
rotate_head_by The Magnebot doesn't have a head. However, the Magnebot API constrains the camera rotation in a similar manner to this command.
set_avatar_collision_detection_mode ArticulationBody doesn't have a collision detection mode parameter.
set_avatar_color
set_stickiness Magnets don't have discrete "sides" that can individually be "magnetized".