Setting object skins from the scripts

***** IMPORTANT NOTE -- START *****

The code below was written for and tested with the Release_1_1_1 version of TGE.

Later versions of TGE handle tagged strings differently, and the code shown below WILL NOT WORK with later versions.

I've modified the current version of TGE (as of 5/5/02) to include this code, with the necessary changes to deal with the new style of tagged strings. So if you checkout or update from CVS now you should have this functionality available to you.

You can still use some of the scripting ideas described in the article and comments below, but there are two important differences that you should be aware of:

1) The function that you invoke on the object-to-be-reskinned is now called setSkinName, rather than setSkin.

2) You do not need to send the strings over ahead of time to "prefetch" them any more.

Otherwise the reskinning code in the latest TGE codebase should behave like the code described here.

As always, if there are problems, let me know in the comments or in email.

***** IMPORTANT NOTE -- END *****


Desired functionality

When setting the team skin for a particular object, we only want to be required to supply some team identifier. We shouldn't be required to know the name of the current skin texture, or what path the textures are located at, or even what type of object we are skinning (beyond the fact that it must be derived from ShapeBase). We also want the capability to specify that some skin textures change when the team changes, and some skin textures do not.


Naming convention

To help achieve these objectives, we'll use a Tribes-like nomenclature where the root of a skin texture filename consists of a team identifier and an object identifier, separated by a period. So, for example, a player object might have skin textures (PNG graphics) named red.player.png, aliens.player.png, and swat-team.player.png, if "red", "aliens", and "swat-team" identify the teams that those skins are for. A flag object might have skins red.flag.png, aliens.flag.png, and swat-team.flag.png. Etc. (The current TGE code looks like it's trying to work with that sort of nomenclature, but it has some problems, particularly when dealing with file paths.)

A single model could use multiple skin textures to cover various parts of the model, of course. Instead of aliens.player.png for covering the entire player with the aliens team skin, the model might use aliens.player-head.png and aliens.player-body.png for skinning two different sections. No problem.

Along with the identifiers for the specific teams of objects that may be used in our game, there's also a special identifier called "base". The "base" identifier marks a texture that should be changed when a new team identifier is specified for the object's skin. The textures with the "base" identifier are the ones that are actually used when creating the model.

A model can also use a texture name that does not start with any identifier at all; that texture will remain constant regardless of team.

Let's go back to the example of the player model that uses two textures for its head and body sections. If the texture player-head.png is used to skin the head, then the head appearance will remain constant across team changes, since that texture does not start with an identifier. If the body texture, on the other hand, was base.player-body.png, then it would be changed on team changes; i.e. if we specified "aliens" as the new team identifier for that player's skin, then its body texture would change to aliens.player-body.png.

The "base" textures should actually exist, for use in those occasions when an object has not had a team identifier set for its skin. Also, each set of team skin textures must reside in the same folder as its "base" texture.

(If you want a string of characters other than "base" to be used as the special identifier, then that's easily changed at a couple of locations in the code.)


Engine code changes

Here's the implementation, file by file. When describing which lines to change, I'm referring to TGE version 1.1.1 (don't know if any of this code has changed since then). I should mention that we don't currently have any preferences that override the skinning behavior, so our code doesn't use ShapeBase::sUsePrefSkins or its scripting counterpart $pref::usePrefSkins. If you want to have some preference setting that changes the skinning behavior you'll need to add it to the code shown here.


*** platform*/*Strings.cc

1) We need to add a support function, dStrncat, so let's get that out of the way first. You'll see later where this is used (dealing with texture file pathnames). Add this same code to platformMacCarb/macCarbStrings.cc, platformWin32/winStrings.cc, and platformX86UNIX/x86UNIXStrings.cc, right below Strcat:

char* dStrncat(char *dst, const char *src, U32 len)
{
   return strncat(dst,src,len);
}

2) Also add a prototype for this function below the one for Strcat in platform/platform.h.

extern char*       dStrncat(char* dst, const char* src, U32 len);

3) You can remove the existing dStrncat prototype in platformX86UNIX.h.


*** ts/tsShapeInstance.h

1) There was some reskinning-related code in ShapeBase; we're going to move it into TSShapeInstance instead, and change and expand it. So add this to the public signature of TSShapeInstance (I put it right below the declaration of ownMaterialList):

void reSkin(const char *newBase);

*** ts/tsShapeInstance.cc

1) And now let's add the implementation of that. I added this under the cloneMaterialList function:

static bool makeSkinPath(char* buffer, U32 bufferLength, const char* resourcePath,
                         const char* oldSkin, const char* oldRoot, const char* newRoot)
{
   bool replacedRoot = true;

   U32 oldRootLen = 0;
   char* rootStart = NULL;

   if (oldRoot == NULL) {
      // Not doing any replacing.
      replacedRoot = false;
   }
   else {
      // See if original name has the old root in it.
      oldRootLen = dStrlen(oldRoot);
      AssertFatal((oldRootLen + 1) < bufferLength, "makeSkinPath: Error, skin root name too long");
      dStrcpy(buffer, oldRoot);
      dStrcat(buffer, ".");
      rootStart = dStrstr(oldSkin, buffer);
      if (rootStart == NULL) {
         replacedRoot = false;
      }
   }

   // Find out how long the total pathname will be.
   const U32 oldLen = dStrlen(oldSkin);
   U32 pathLen = 0;
   if (resourcePath != NULL) {
      pathLen = dStrlen(resourcePath);
   }
   if (replacedRoot) {
      const U32 newRootLen = dStrlen(newRoot);
      AssertFatal((pathLen + 1 + oldLen + newRootLen - oldRootLen) < bufferLength, "makeSkinPath: Error, pathname too long");
   }
   else {
      AssertFatal((pathLen + 1 + oldLen) < bufferLength, "makeSkinPath: Error, pathname too long");
   }

   // OK, now make the pathname.

   // Start with the resource path:
   if (resourcePath != NULL) {
      dStrcpy(buffer, resourcePath);
      dStrcat(buffer, "/");
   }
   else {
      buffer[0] = '[[6281f467969b7]]';
   }
   if (replacedRoot) {
      // Then the pre-root part of the old name:
      U32 rootStartPos = rootStart - oldSkin;
      if (rootStartPos != 0) {
         dStrncat(buffer, oldSkin, rootStartPos);
      }
      // Then the new root:
      dStrcat(buffer, newRoot);
      dStrcat(buffer, ".");
      // Then the post-root part of the old name:
      dStrcat(buffer, oldSkin + rootStartPos + oldRootLen + 1);
   }
   else {
      // Then the old name:
      dStrcat(buffer, oldSkin);
   }

   return replacedRoot;
}


void TSShapeInstance::reSkin(const char *newBase)
{
#define NAME_BUFFER_LENGTH 256
   static char pathName[NAME_BUFFER_LENGTH];

   if (newBase == NULL) {
      return;
   }

   // Make our own copy of the materials list from the resource
   // if necessary.
   if (ownMaterialList() == false) {
      cloneMaterialList();
   }

   const char* resourcePath = hShape.getFilePath();

   // Cycle through the materials.
   TSMaterialList* pMatList = getMaterialList();
   for (U32 j = 0; j < pMatList->mMaterialNames.size(); j++) {
      // Get the name of this material.
      const char* pName = pMatList->mMaterialNames[j];
      // Bail if no name.
      if (pName == NULL) {
         continue;
      }
      // Make a texture file pathname with the new root if this name
      // has the old root in it; otherwise just make a path with the
      // original name.
      bool replacedRoot = makeSkinPath(pathName, NAME_BUFFER_LENGTH, resourcePath,
                          pName, (const char*)"base", newBase);

      if (!replacedRoot) {
         // If this wasn't in the desired format, set the material's
         // texture handle (since that wasn't copied over in the
         // cloning) and continue.
         pMatList->mMaterials[j] = TextureHandle(pathName, MeshTexture, false);
         continue;
      }

      // OK, it is a skin texture.  Get the handle.
      TextureHandle skinHandle = TextureHandle(pathName, MeshTexture, false);
      // Do a sanity check; if it fails, use the original skin instead.
      if (skinHandle.getGLName() != 0) {
         pMatList->mMaterials[j] = skinHandle;
      }
      else {
         makeSkinPath(pathName, NAME_BUFFER_LENGTH, resourcePath, pName, NULL, NULL);
         pMatList->mMaterials[j] = TextureHandle(pathName, MeshTexture, false);
      }
   }
}

BTW, the hardcoded string "base" in TSShapeInstance::reSkin is one of the two locations where that appears, if you're interested in changing the code to use something other than "base" as the special identifier. The other instance is in ShapeBase::checkTags below.


*** game/shapeBase.h

1) Replace these lines

U32 mSkinTag;
   U32 mSkinPrefTag;

with these lines:

U32 mSkinLocalTag;
   U32 mSkinRemoteTag;
   U32 mSkinDesiredRemoteTag;

You can also remove the declaration of sUsePrefSkins if, like us, you're not using it.

These variables will hold the tags for the tagged strings that are our team identifiers. mSkinRemoteTag is the tag for the team identifier string received by the client from the server, and mSkinLocalTag is the tag for the team identifier string according to the local process (client or server). mSkinDesiredRemoteTag holds the tag for the most recent team identifier sent over, for a skin change request that may or may not have happened yet.

2) We also need to add a ghost update mask bit so that we can indicate when the server should propagate a skin change to the client, so replace this line:

SoundMaskN      = Parent::NextFreeMask << 7,       // Extends + MaxSoundThreads bits

with these lines:

SkinMask        = Parent::NextFreeMask << 7,
      SoundMaskN      = Parent::NextFreeMask << 8,       // Extends + MaxSoundThreads bits

3) Final change to this header file is to add this under the prototype of checkTags:

void setSkinTag(S32 skinTag) { if (mSkinLocalTag != skinTag) { mSkinLocalTag = skinTag; setMaskBits(SkinMask); } }

That's the function we'll use to request the skin change on the server and set things in motion.


*** game/shapeBase.cc

1) Again, if you're not going to be implementing any code to deal with "skin prefs", you might want to remove any lines that reference sUsePrefSkins (there are two).

2) Then, in the constructor for ShapeBase, replace these lines:

mSkinTag = 0;
   mSkinPrefTag = 0;

with these lines:

mSkinLocalTag = 0;
   mSkinRemoteTag = 0;
   mSkinDesiredRemoteTag = 0;

3) Remove the reSkin function that existed in this file, as we're going to be using our new TSShapeInstance member function for that instead.

4) In ShapeBase::onNewDataBlock, replace these lines:

if (isGhost() && mSkinTag)
    {
       reSkin(mShapeInstance, gNetStringTable->lookupString(mSkinTag),
              mSkinPrefTag ? gNetStringTable->lookupString(mSkinPrefTag) : "");
       mSkinHash = (_StringTable::hashString(gNetStringTable->lookupString(mSkinTag)) ^   
                    _StringTable::hashString(mSkinPrefTag ? gNetStringTable->lookupString(mSkinPrefTag) : ""));   
    }

with these:

if (isGhost() && mSkinLocalTag && mShapeInstance) {
      const char* nameString = gNetStringTable->lookupString(mSkinLocalTag);
      mShapeInstance->reSkin(nameString);
      mSkinHash = _StringTable::hashString(nameString);
   }

(remember, we're not using "skin prefs").

5) ShapeBase::checkTags will need some changes as well, but rather than treat those individually, here's the whole function:

void ShapeBase::checkTags()
{
   NetConnection *tosv = NetConnection::getServerConnection();
   if (!tosv) {
      return;
   }
   bool repost = false;
   
   // Resolve the object's name
   if (mNameTag) {
      if (U32 localTag = tosv->translateRemoteStringId(mNameTag)) {
         mShapeName = gNetStringTable->lookupString(localTag);
      }
      else {
         repost = true;
      }
   }
   else {
      mShapeName = 0;
   }

   // Check for skin update.
   if ((mSkinRemoteTag != mSkinDesiredRemoteTag) && mSkinDesiredRemoteTag) {
      if (U32 localTag = tosv->translateRemoteStringId(mSkinDesiredRemoteTag)) {
         mSkinLocalTag = localTag;
         mSkinRemoteTag = mSkinDesiredRemoteTag;
         const char* skinName = gNetStringTable->lookupString(mSkinLocalTag);
         if (mShapeInstance && skinName) {
            mShapeInstance->reSkin(skinName);
            mSkinHash = _StringTable::hashString(skinName);
         }
      }
      else {
         repost = true;
      }
   }

   // Now check the images
   for (int i = 0; i < MaxMountedImages; i++) {
      MountedImage& image = mMountedImageList[i];
      if (image.dataBlock && image.skinTag != image.desiredTag) {
         const char *newBase = NULL;
         if (image.desiredTag) {
            U32 localTag = tosv->translateRemoteStringId(image.desiredTag);
            if (localTag) {
               newBase = gNetStringTable->lookupString(localTag);
            }
            else {
               repost = true;
            }
         }
         else {
            newBase = "base";
         }

         // Have a new tag, so we need to re-skin the object
         image.skinTag = image.desiredTag;
         if (image.shapeInstance) {
            image.shapeInstance->reSkin(newBase);
         }
      }
   }

   // Try again later if we didn't get them all
   if (repost) {
      Sim::postEvent(this, new CheckSkinEvent, Sim::getCurrentTime() + 1000);
   }
}

Note the other occurrence of the hardcoded string "base" above.

6) Now we need to modify slightly the conditions under which checkTags will be called. In ShapeBase::packUpdate, replace these lines:

if(!stream->writeFlag(mask & (NameMask | DamageMask | SoundMask |
         ThreadMask | ImageMask | CloakMask | MountedMask | InvincibleMask |
         ShieldMask)))
      return retMask;

with these:

if(!stream->writeFlag(mask & (NameMask | DamageMask | SoundMask |
         ThreadMask | ImageMask | CloakMask | MountedMask | InvincibleMask |
         ShieldMask | SkinMask)))
      return retMask;

I.e., all you're doing is adding SkinMask to the set of update conditions there.

7) Similarly, replace these lines from that function:

// Group some of the uncommon stuff together.
   if (stream->writeFlag(mask & (NameMask | ShieldMask | CloakMask | InvincibleMask))) {

with these:

// Group some of the uncommon stuff together.
   if (stream->writeFlag(mask & (NameMask | ShieldMask | CloakMask | InvincibleMask | SkinMask))) {

8) Even further down in that same function, below the block of code that sends out mInvincibleTime and mInvincibleSpeed, add this block:

if (stream->writeFlag(mask & SkinMask)) {
         stream->writeInt(mSkinLocalTag, NetStringTable::StringIdBitSize);
         con->checkString(mSkinLocalTag);
      }

9) Then in ShapeBase::unpackUpdate, those values need to be read. So, below the block of code that reads the invincibility info (the block marked with the "// InvincibleMask" comment), add this block:

if (stream->readFlag()) {  // SkinMask
         S32 skinTag = stream->readInt(NetStringTable::StringIdBitSize);
         checkTagsNeeded = true;
         if (mSkinDesiredRemoteTag != skinTag) {
            mSkinDesiredRemoteTag = skinTag;
         }
      }

10) That completes the code necessary to make the right things happen when the server calls setSkinTag. So our final addition to the engine code is a script access point for using that function. Down among the console hooks defined at the bottom of the file (I put this just after the definition for setShadowDetailLevel), add this code:

ConsoleMethod(ShapeBase, setSkin, bool, 3, 3, "obj.setSkin(skinTag);")
{
   const char* skinName = argv[2];

   // If they sent us a legal skin tag, grab it.
   if (skinName[0] == StringTagPrefixByte) {
      ShapeBase* shape = static_cast<ShapeBase*>(object);
      S32 skinTag = dAtoi(skinName + 1);
      shape->setSkinTag(skinTag);
      return true;
   }

   return false;
}

Reskinning non-ShapeBase objects

As I mentioned before, and as the code indicates, this solution is for reskinning objects that are derived from ShapeBase. However, most of the interesting code is in TSShapeInstance, so any object that is displayed using a TSShapeInstance could be reskinned if you add code to that object's class similar to the code I added to ShapeBase; i.e., setting a team skin tag on the server, transmitting it to the client ghost, and calling reSkin appropriately.


Using this in the scripting

In my player creation code, I have this:

%player.setSkin(Game.teamSkin[%player.team]);

where %player is an identifier for a newly created Player object, and Game.teamSkin is an array I constructed elsewhere that contains the team skin identifiers as tagged strings. With this team skin setup, you must use a tagged string as an argument to setSkin. A tagged string is enclosed in single quotes rather than double quotes, which associates it with an identifier that will be transmitted over the server/client connection rather than having to transmit the whole string.

One slightly annoying problem is that the tagged strings are sent to the server on demand. So, the first time you use a given skin, there will be a one second delay before it is applied to the object, as the server has to send the tagged string to the client first. This delay is adjustable (it's the "1000" value at the end of checkTags), but if you're a little clever you won't have to have any delay at all. What you can do is send over the tagged strings for team skin identifiers ahead of time, before any team skinning happens. In serverCmdMissionStartPhase1Ack, before sending the CRC value, I do

// Send any net strings that the client will need right away.
   %client.sendNetStrings();

This calls the following function I created:

// Called after the client gets the mission file, to send any important
// net strings immediately.
function GameConnection::sendNetStrings(%this)
{
   for (%i = 1; %i <= Game.numTeams; %i++) {
      commandToClient(%this, 'PrefetchNetString', Game.teamSkin[%i]);
   }
}

Game.numTeams is set elsewhere to the number of teams in the mission. The PrefetchNetString command means that this function gets invoked on the receiving client:

function clientCmdPrefetchNetString(%string)
{
   // Does nothing, just exists to get the strings sent.
}

The side effect of transmitting the tag for its string argument is all that I need out of this command, so the function doesn't do anything else.

Other objects besides players can have team skins. In our project, if an object is to be "teamed", it is placed in a SimGroup that has a name indicating which team number it belongs to. Just before the mission starts, our scripting calls setTeam on each such SimGroup, with its team number as an argument. That executes SimGroup::setTeam, which can also call setTeam on other types of objects; the relevant code:

// "Set team" functions for types of objects.
// SimObject:: just set the team field.
function SimObject::setTeam(%this, %team)
{
   %this.team = %team;
}
// SimGroup: call setTeam on each contained object.
function SimGroup::setTeam(%this, %team)
{
   Parent::setTeam(%this, %team);
   for (%i = 0; %i < %this.getCount(); %i++) {
      %obj = %this.getObject(%i);
      %obj.setTeam(%team);
   }
}
// ShapeBase: set the team skin, if the object has one.
function ShapeBase::setTeam(%this, %team)
{
   Parent::setTeam(%this, %team);
   %this.setSkin(Game.teamSkin[%team]);
}

So, if you call setTeam on a SimGroup, it will call setTeam on each contained object. Any object that has setTeam called on it will set its ".team" field to the indicated team number (which isn't related to skinning BTW, just a useful thing to have). ShapeBase objects also get their team skins set, if they have them.

I think that about covers it... I'd be interested in hearing what happens if anyone else gives this a try. I've tried to reconstruct all the necessary changes by checking our CVS logs; I think I got everything. Fingers crossed. :-)