Overcoming ITickable's Limitations

ICSTickable::advanceClientTime(timeDelta);

ICSTickable::advanceServerTime(timeDelta);

#ifndef _ICSTICKABLE_H_
#define _ICSTICKABLE_H_

#include "core/tVector.h"

/// This interface allows you to let any object be ticked, and is based on TGE 1.4's
/// ITickable class. The difference is ICSTickable allows for an object to be processed
/// on the server or client side.  You use it like so:
/// @code
/// class FooClass : public SimObject, public virtual ICSTickable
/// {
///    // You still mark SimObject as Parent
///    typdef SimObject Parent;
/// private:
/// ...
///
/// protected:
///    // These three methods are the interface for ICSTickable
///    virtual void interpolateTick( F32 delta );
///    virtual void processTick();
///    virtual void advanceTime( F32 timeDelta );
///
/// public:
/// ...
/// };
/// @endcode
/// Please note the three methods you must implement to use ICSTickable, but don't
/// worry. If you forget, the compiler will tell you so. Also note that the
/// typedef for Parent should NOT BE SET to ICSTickable, the compiler will <i>probably</i>
/// also tell you if you forget that. Last, but assuridly not least is that you note
/// the way that the inheretance is done: public <b>virtual</b> ICSTickable
/// It is very important that you keep the virtual keyword in there, otherwise
/// proper behavior is not guarenteed. You have been warned.
///
/// The point of a tickable object is that the object gets ticks at a fixed rate
/// which is one tick every 32ms. This means, also, that if an object doesn't get
/// updated for 64ms, that the next update it will get two-ticks. Basically it
/// comes down to this. You are assured to get one tick per 32ms of simulation time
/// passing provided that isProcessingTicks returns true when ICSTickable calls it.
///
/// The processTick() method that provides the 32ms tick is called for both client
/// and server objects.
///
/// isProcessingTicks is a virtual method and you can (should you want to)
/// override it and put some extended functionality to decide if you want to
/// recieve tick-notification or not.
///
/// The remaining two methods of time notification are only called on the client.
/// advanceTime lets you know when time passes regardless of the return value
/// of isProcessingTicks. The object WILL get the advanceTime call every single
/// update. The argument passed to advanceTime is the time since the last call
/// to advanceTime. Updates are not based on the 32ms tick time. Updates are
/// dependant on framerate. So you may get 200 advanceTime calls in a second, or you
/// may only get 20. There is no way of assuring consistant calls of advanceTime
/// like there is with processTick. Both are useful for different things, and
/// it is important to understand the differences between them.
///
/// Interpolation is the last part of the ICSTickable interface on the client side.
/// It is called every update, as long as isProcessingTicks evaluates to true on the
/// object. This is used to interpolate between 32ms ticks. The argument passed to
/// interpolateTick is the time since the last call to processTick. You can see in the
/// code for ICSTickable::advanceClientTime that before a tick occurs it calls
/// interpolateTick(0) on every object. This is to tell objects which do interpolate
/// between ticks to reset their interpolation because they are about to get a new tick.
///
/// To place an object onto the client or server processing list, a call to
/// addObjectToTickList() is required. An object may only belong to one list at a time
/// and will automatically be removed from any existing list. This method may be called
/// at any time, but must be prior to the need for tick processing.  A common location
/// would be in the class's constructor, or during the SimObject onAdd() method.
///
/// When an object is to be removed from a processing list, such as when it is deleted,
/// a call to removeObjectFromTickList() is required.  This could be performed in the
/// class's destructor, or during the SimObject onRemove() method.
///
/// The following example illustrates how to perform this with a NetObject:
/// @code
/// bool FooClass::onAdd()
/// {
///    if (!Parent::onAdd())
///       return false;
///
///    addObjectToTickList(isClientObject());
///
///    return true;
/// }
///
/// void FooClass:onRemove()
/// {
///    removeObjectFromTickList();
///
///    Parent::onRemove();
/// }
/// @endcode
/// In the example, the NetObject's isClientObject() method is used to determine if it should
/// be added to the client list or the server list.
///
/// ICSTickable checks if an object deletes itself in the middle of tick processing and
/// ensures that no objects lose a tick due to the processing lists being reshuffled.  The
/// assumption here is that an object will only delete itself during a processTick() or
/// advanceTime().  It would not make sense for an object to delete itself during an
/// interpolateTick().
///
/// @todo Support processBefore/After and move the GameBase processing over to use ICSTickable
class ICSTickable
{
private:
   static U32 smLastClientTick;  ///< Time of the last tick that occurred
   static U32 smLastClientTime;  ///< Last time value at which advanceTime was called
   static U32 smLastClientDelta; ///< Last delta value for advanceTime
   static U32 smLastServerTick;  ///< Time of the last tick that occurred
   static U32 smLastServerTime;  ///< Last time value at which advanceTime was called
   static U32 smLastServerDelta; ///< Last delta value for advanceTime

   // This just makes life easy
   typedef Vector<ICSTickable *>::iterator ProcessListIterator;
   static Vector<ICSTickable *>& getClientProcessList(); ///< List of client tick controls
   static Vector<ICSTickable *>& getServerProcessList(); ///< List of server tick controls

protected:
   bool mProcessTick; ///< Set to true if this object wants tick processing

   /// Determines which processing list the object has been placed on.
   /// 0=Does not belong to a list (the default)
   /// 1=Client processing list
   /// 2=Server processing list
   S32 mProcessingList;

   /// Called within the object's onAdd() to place it in the
   /// appropriate processing list.
   /// @parm   client     True if this object should be placed on the client list
   void addObjectToTickList(bool client);

   /// Called within the object's onRemove() to remove it
   /// from the processing lists.
   void removeObjectFromTickList();

   /// This method is called every frame for a client object and lets the object
   /// interpolate between ticks so you can smooth things as long as
   /// isProcessingTicks returns true when it is called on the object.  An object
   /// may not delete itself within this method, such as by using deleteObject().
   virtual void interpolateTick( F32 delta ) = 0;

   /// This method is called once every 32ms if isProcessingTicks returns true
   /// when called on the object and is called on both client and server objects.
   virtual void processTick() = 0;

   /// This method is called once every frame for a client object regardless of
   /// the return value of isProcessingTicks and informs the object of the passage
   /// of time.  This may be used to advance client side animations.
   virtual void advanceTime( F32 timeDelta ) = 0;

public:
   // Can let everyone look at these if they want to
   static const U32 smTickShift;    ///< Shift value to control how often Ticks occur
   static const U32 smTickMs;       ///< Number of milliseconds per tick, 32 in this case
   static const F32 smTickSec;      ///< Fraction of a second per tick
   static const U32 smTickMask;

/// Constructor
   /// Initialized to not belong to a processing list
   ICSTickable();

   /// Destructor
   /// Remove this object from the processing list if it hasn't already done so.
   virtual ~ICSTickable();

   /// Is this object wanting to receive tick notifications
   /// @returns True if object wants tick notifications
   virtual bool isProcessingTicks() const { return mProcessTick; };

   /// Sets this object as either tick processing or not
   /// @parm   tick     True if this object should process ticks
   virtual void setProcessTicks( bool tick = true );

//------------------------------------------------------------------------------

   /// This is called in clientProcess to advance the time for all ICSTickable
   /// client objects
   /// @returns True if any ticks were sent
   /// @see clientProcess
   static bool advanceClientTime( U32 timeDelta );

   /// This is called in serverProcess to advance the time for all ICSTickable
   /// server objects
   /// @returns True if any ticks were sent
   /// @see serverProcess
   static bool advanceServerTime( U32 timeDelta );
};

//------------------------------------------------------------------------------

inline void ICSTickable::setProcessTicks( bool tick /* = true  */ )
{
   mProcessTick = tick;
}

#endif // _ICSTICKABLE_H_

#include "core/iCSTickable.h"

// The statics
U32 ICSTickable::smLastClientTick = 0;
U32 ICSTickable::smLastClientTime = 0;
U32 ICSTickable::smLastClientDelta = 0;
U32 ICSTickable::smLastServerTick = 0;
U32 ICSTickable::smLastServerTime = 0;
U32 ICSTickable::smLastServerDelta = 0;

const F32 ICSTickable::smTickSec = ( F32( ICSTickable::smTickMs ) / 1000.f );
const U32 ICSTickable::smTickShift = 5;
const U32 ICSTickable::smTickMs = ( 1 << smTickShift );
const U32 ICSTickable::smTickMask = ( smTickMs - 1 );

Vector<ICSTickable *>& ICSTickable::getClientProcessList()
{
   // This helps to avoid the static initialization order fiasco
   static Vector<ICSTickable *> smClientProcessList; // List of client tick controls
   return smClientProcessList;
}

Vector<ICSTickable *>& ICSTickable::getServerProcessList()
{
   // This helps to avoid the static initialization order fiasco
   static Vector<ICSTickable *> smServerProcessList; // List of server tick controls
   return smServerProcessList;
}

//------------------------------------------------------------------------------

ICSTickable::ICSTickable()
{
   mProcessingList = 0;
}

//------------------------------------------------------------------------------

ICSTickable::~ICSTickable()
{
   // Make sure that the object has been removed from any processing list.
   // Tsk, tsk.  The object should clean up itself.  Maybe do an assert?
   removeObjectFromTickList();
}

//------------------------------------------------------------------------------

void ICSTickable::addObjectToTickList(bool client)
{
   if(client)
   {
      // If we're already on the client list, return.
      if(mProcessingList == 1)
         return;

      // If we're already on another list, first remove
      // ourselves from it.
      if(mProcessingList)
         removeObjectFromTickList();

      // Add to the client processing list
      getClientProcessList().push_back(this);
      mProcessingList = 1;

   } else
   {
      // If we're already on the server list, return.
      if(mProcessingList == 2)
         return;

      // If we're already on another list, first remove
      // ourselves from it.
      if(mProcessingList)
         removeObjectFromTickList();

      // Add to the server processing list
      getServerProcessList().push_back(this);
      mProcessingList = 2;
   }
}

//------------------------------------------------------------------------------

void ICSTickable::removeObjectFromTickList()
{
   if(!mProcessingList)
      return;

   if(mProcessingList == 1)
   {
      for( ProcessListIterator i = getClientProcessList().begin(); i != getClientProcessList().end(); i++ )
      {
         if( (*i) == this )
         {
            getClientProcessList().erase( i );
            mProcessingList = 0;
            return;
         }
      }

   } else if(mProcessingList == 2)
   {
      for( ProcessListIterator i = getServerProcessList().begin(); i != getServerProcessList().end(); i++ )
      {
         if( (*i) == this )
         {
            getServerProcessList().erase( i );
            mProcessingList = 0;
            return;
         }
      }
   }
}

//------------------------------------------------------------------------------

bool ICSTickable::advanceClientTime( U32 timeDelta )
{
   U32 targetTime = smLastClientTime + timeDelta;
   U32 targetTick = ( targetTime + smTickMask ) & ~smTickMask;
   U32 tickCount = ( targetTick - smLastClientTick ) >> smTickShift;

   // Storage to keep track of the last processed object
   ICSTickable* obj;

   // If we are going to send a tick, call interpolateTick(0) so that the objects
   // will reset back to their position at the last full tick
   if( smLastClientDelta && tickCount )
      for( ProcessListIterator i = getClientProcessList().begin(); i != getClientProcessList().end(); i++ )
         if( (*i)->isProcessingTicks() )
            (*i)->interpolateTick( 0.f );

   // Advance objects
   if( tickCount )
      for( ; smLastClientTick != targetTick; smLastClientTick += smTickMs )
         for( ProcessListIterator i = getClientProcessList().begin(); i < getClientProcessList().end(); )
            if( (*i)->isProcessingTicks() )
			{
               // Store the current object
               obj = (*i);

			   // Process the object's tick
               (*i)->processTick();

               // Check if we should advance the iterator.  Don't if the processed
               // object has deleted itself.
               if(obj == (*i))
                  ++i;

			} else
			{
               // Advance the iterator
               ++i;
			}

   smLastClientDelta = ( smTickMs - ( targetTime & smTickMask ) ) & smTickMask;
   F32 dt = smLastClientDelta / F32( smTickMs );

   // Now interpolate objects that want ticks
   for( ProcessListIterator i = getClientProcessList().begin(); i != getClientProcessList().end(); i++ )
      if( (*i)->isProcessingTicks() )
         (*i)->interpolateTick( dt );


   // Inform ALL objects that time was advanced
   dt = F32( timeDelta ) / 1000.f;
   for( ProcessListIterator i = getClientProcessList().begin(); i < getClientProcessList().end(); )
   {
      // Store the current object
      obj = (*i);

      // Process the object
      (*i)->advanceTime( dt );

      // Check if we should advance the iterator.  Don't if the processed
      // object has deleted itself.
      if(obj == (*i))
         ++i;
   }

   smLastClientTime = targetTime;

   return tickCount != 0;
}
//------------------------------------------------------------------------------

bool ICSTickable::advanceServerTime( U32 timeDelta )
{
   U32 targetTime = smLastServerTime + timeDelta;
   U32 targetTick = ( targetTime + smTickMask ) & ~smTickMask;
   U32 tickCount = ( targetTick - smLastServerTick ) >> smTickShift;

   // Storage to keep track of the last processed object
   ICSTickable* obj;

   // Advance objects
   if( tickCount )
      for( ; smLastServerTick != targetTick; smLastServerTick += smTickMs )
         for( ProcessListIterator i = getServerProcessList().begin(); i < getServerProcessList().end(); )
            if( (*i)->isProcessingTicks() )
			{
               // Store the current object
               obj = (*i);

			   // Process the object's tick
               (*i)->processTick();

               // Check if we should advance the iterator.  Don't if the processed
               // object has deleted itself.
               if(obj == (*i))
                  ++i;

			} else
			{
               // Advance the iterator
               ++i;
			}

   smLastServerDelta = ( smTickMs - ( targetTime & smTickMask ) ) & smTickMask;

   smLastServerTime = targetTime;

   return tickCount != 0;
}