An alternative to PathShape

I started out intending to look into the widely reported jittering issue with the PathShape resource. I never really got very far into it. It's really two resources rolled into one. It provides a shape class that can be moved along a predefined path and the ability for players to walk on the shape while it's moving. I decided to separate those two features so I could look at the jittering issue in isolation from the classes providing movement. I also wanted to see if I could recreate the functionality without modifying core engine files (...I couldn't, but they have been reduced). After a failed start, two re-writes and many hours analyzing debug spew, I finally have some code to share. You can get it here:
github.com/OTHGMars/Torque3D/tree/walkable_shapes

In Brief...

I'm calling this resource WalkableShapes (I'm open to suggestions for better class names). It provides three classes that can be used in games. TSPathShape is a simple path following shape. TSAttachable builds on TSPathShape to add the ability for players to walk on the shape while it's moving. The script interface for this class is almost identical to the traditional PathShape. The setup is slightly different. Since the DataBlock has been eliminated, the shape file is set in the editor. The WalkableShape class is a simple shape object that players can walk on while it's moving. It provides no movement of it's own, but can be mounted to...Anything! So if you want to walk on the back of a flatbed truck, model the bed as a separate shape and mount it to the truck in game as a WalkableShape. It can be mounted to any shape that provides movement. There is a demo level included that has a platform-jumping mini-game and a Cheetah with a platform mounted to the roof where the turret normally mounts. You'll need two connections to try that though.

It's still a work-in-progress. Anyone that wants to contribute changes or suggest improvements, please do so.

Testing in other builds

This resource should be compatible with all of the MIT T3D builds and possibly earlier. If you test in another build, please post your results here. To add to another build, you'll need the three engine changes, here, here and here. There are 8 new source code files that need to be included in your build. They do not need to be in the T3D directory. They can be compiled from your project/source directory for easy testing and removal. You'll also want to add the script files and demo level.

The Class Details

TSDynamic (tsDynamic.h, tsDynamic.cpp)
I wanted to base my path shape off the TSStatic class because it is so simple and lightweight, but unfortunately it wouldn't work well because it's networking was designed to be static and doesn't pack updates to clients efficiently. TSDynamic is just a renamed copy of TSStatic with a couple very minor modifications.

TSPathShape (tsPathShape.h, tsPathShape.cpp)
This class duplicates the movement features of the PathShape resource with none of the attachment code. All of the console methods are backward compatible with PathShape so it will be simple to modify existing scripts. It can handle looping paths without stopping on the last node and waiting to be restarted from script. I added a console method setLooping() so that can be turned on or off from script. I also added an onTargetReached() callback.
This can be a handy class for simple moving objects like a door that swings or slides. Motion can be started and stopped from script and it will fire callbacks when destinations are reached. It can also stop ticking when not in motion, making it almost as lightweight as a TSStatic when parked.

TSAttachable (tsAttachable.h, tsAttachable.cpp)
This class inherits TSPathShape and provides all of the attachment functionality of the PathShape resource. Three console methods have been added for managing the attachments, attachObject(obj), detatchObject(obj) and detachAll(). Any SceneObject derived class can be attached.
Two console variables have been added: UseAutoAttach (Bool) When this is true it will scan for objects directly above it and automatically attach any that are found. When false, objects must be explicitly attached from script. RayLength (F32) This is the length of raycast directly below attached objects when checking to see if they have fallen off. This is also the distance above the shape to scan when using auto-attach.
Two callback methods onObjectAttached(obj) and onObjectDetached(obj) have been added to provide a script notification anytime an object attaches to or detaches from the shape. These callbacks fire even if the object was manually attached from script.

WalkableShape (walkableShape.h, walkableShape.cpp)
This class provides the identical script interface as TSAttachable based on a TSDynamic object instead of TSPathShape. This class really renders TSAttachable obsolete since you could mount a WalkableShape onto a TSPathShape and get an identical result (from the users perspective). I have left TSAttachable in the resource since it's the replacement for the shape provided by the original PathShape resource.

The Jitters

There were a number of issues trying to synchronize a local client player object with a moving shape. A pathed shape that can tick it's position on the client was a great shape to test against. It knows precisely where it's supposed to be at every tick. The Player is interpreting a move locally and periodically (every readPacketData()) synchronising it's position with the server. That subtle adjustment becomes a huge jump when riding at high speed on a shape when the player is warped to the server location. This is the lone reason engine changes were required for this resource (the CameraSpline change is purely cosmetic). The Player class needs to know it's attached and bypass the warp in readPacketData() and unpackUpdate(). That warp is crucial though. The player needs to represent location and orientation correctly on the client or your bullets won't go where you aimed. So the walkable classes update the players position in local coordinates and rotation relative to the shape they're mounted on at the same frequency that they'd get adjusted in readPacketData(). If the shape they're on warps, they warp with it.

Areas that need improvement
The base class needs a collision callback to script. Other object types need tested and adjustments made. I imagine a vehicle as the control object (car on ferry deck?) would have the same jitter issue from warping and need a similar fix.