twSurfaceReference Object

Download Code File

The twSurfaceReference object is a TGE enhancement used to create an accessible reference to the texture/surface characteristics of any point on a terrain.

The example included provides code fragments that allows you to modify the fxGrassReplicator to use this capability.

You must have the fxGressReplicator by Bendik Stang already installed in your game.

You can also apply the same changes to all of the replicator objects created by Melv May to get them to work the same way.

This resource assumes that you are familiar with the fxGrassReplicator, TGE, VC++, C++ programming, TGE script programming and the example scripts. If you are familiar with these things, then you should be able to resolve any conflicts that arise with these changes. If you have made changes or enhancements to any of the TGE source code or scripts, I can't warrant that this resource will work.



Installation
============

Back up your game source code and scripts prior to installation of this enhancement.


Engine Source changes
---------------------
1. Copy the files:


twSurfaceReference.cc
twSurfaceReference.h

from the twStructureReference.zip into the engine directory where your
fxGrassReplicator files reside.



2. Add both files to your TGE project.



3. Open fxGrassReplicator.cc

3a. Add this include to near the end of the includes at the top,

[b]
            #include "twSurfaceReference.h"
[/b]

BEFORE the include for fxGrassReplicator.h.



3b. Add this function to any place you like within the file:

[b]
            //--------------------------------------------
            // GetTerrainTextures
            //   (adapted from original code written by James Holmes)
            //
            // Get the terrain texture under an x,y coord
            //
            // Fills an array with the alpha value of each of the
            // textures under that point.
            //
            //   distance - How far to look down for the terrain block
            //   pt - Point in world space
            //   alphas - U8 array of size NUM_SURFACES
            //
            bool fxGrassReplicator::GetTerrainTextures(float distance, Point3F& pt, U8 *alphas)
            {
            RayInfo rInfo;

               if (gClientContainer.castRay(pt, Point3F(pt.x, pt.y, pt.z - distance ), TerrainObjectType, &rInfo))
               {
               U32 CollisionType = rInfo.object->getTypeMask();

                  if (CollisionType & TerrainObjectType)
                  {
            		   TerrainBlock* ter = static_cast<TerrainBlock*>(rInfo.object);
            		   Point2I gPos;
            		   const MatrixF & mat = ter->getTransform();

            		   Point3F origin;
            		   mat.getColumn(3, &origin);
            		   F32 squareSize = (F32) ter->getSquareSize();
            		   F32 halfSquareSize = squareSize / 2;

            		   float x = (pt.x - origin.x + halfSquareSize) / squareSize;
            		   float y = (pt.y - origin.y + halfSquareSize) / squareSize;

            		   ter->getMaterialAlpha(Point2I(x,y), alphas);
            		   return true;
                  }
               }
               return false;
            }
[/b]

3c. Add the following lines to the end of the function initPersistFields()

[b]
	addField( "SurfaceExclusionMode",		TypeBool,		Offset( mFieldData.mSurfaceExclusionMode,			fxGrassReplicator ) );
   addField( "SurfaceType",      TypeEnum,      Offset(mFieldData.mTheSurface,		fxGrassReplicator ), 1, &gSurfaceTypeTable );
[/b]

3d. In the function CreateGrass() AFTER these lines:

[i]
				if ((CollisionType & WaterObjectType) && !mFieldData.mAllowWaterSurface &&
					!gClientContainer.castRay( GrassStart, GrassEnd, FXGRASSREPLICATOR_NOWATER_COLLISION_MASK, &RayEvent)) continue;
[/i]

add the following fragment:

[b]
            if ((twSurfaceReference::ESurfaceType)mFieldData.mTheSurface)  // if we are checking for specific surfaces and not just 'any'
            {
               if ( BaseSurfaces[(twSurfaceReference::ESurfaceType)mFieldData.mTheSurface].isAvailable)
               {
				   CollisionResult = false;
               U8 alphas[TerrainBlock::MaterialGroups];
                  // Checks if the new position is over a blended terrain texture (a 'surface' ) that is *exactly* the same as the surface where
                  // the specified SurfaceReference marker was placed.

                  if (GetTerrainTextures(4000.0f, GrassStart, alphas))
                  {
                  bool skip = mFieldData.mSurfaceExclusionMode;

                     for (int i=0; i < TerrainBlock::MaterialGroups; i++)
                     {
                        if (alphas[ i] != BaseSurfaces[(twSurfaceReference::ESurfaceType)mFieldData.mTheSurface].alphas[ i])
                        {
                           skip = !mFieldData.mSurfaceExclusionMode;                 // even one non-match means this is not the same surface
                           break;
                        }
                     }
                     if (skip) continue;              // don't place grass here
                  }
               }
             }
[/b]

3e. In the function packUpdate() AFTER these lines:

[i]
      		stream->writeFlag(mFieldData.mIsSquare);
      		stream->write(mFieldData.mRotateAngle);
[/i]

add the following fragment:

[b]
      		stream->writeFlag(mFieldData.mSurfaceExclusionMode);					// allow/disallow toggle
            stream->write( mFieldData.mTheSurface );                          // the surface reference
[/b]

3f. In the function unpackUpdate() AFTER these lines:

[i]
      		mFieldData.mIsSquare = stream->readFlag();
      		stream->read(&mFieldData.mRotateAngle);							// if not; use this angle
[/i]

add the following fragment:

[b]
      		mFieldData.mSurfaceExclusionMode = stream->readFlag();				// Allow/Disallow toggle
            stream->read( &mFieldData.mTheSurface);                           // the surface reference
[/b]

4. Open fxGrassReplicator.h

4a. AFTER these lines:

[i]
   		bool				mIsSquare;
   		F32					mRotateAngle;
[/i]

add the following fragment:

[b]
         bool              mSurfaceExclusionMode;              // if 1 then allow, if 0 then disallow
         U32      mTheSurface;
[/b]

4b. AFTER these lines:

[i]
			mIsSquare				= true;
			mRotateAngle			= 0.0f;
[/i]

add the following fragment:

[b]
         mSurfaceExclusionMode			= false;
         mTheSurface            = (U32)twSurfaceReference::eAny;
[/b]

4c. AFTER these lines:

[i]
			public:
			    fxGrassReplicator();
			    ~fxGrassReplicator();"
[/i]

add the following line:

[b]
         bool GetTerrainTextures(float,Point3F&, U8 *);
[/b]

5. Open /engine/console/simBase.h

and add the following line in the nameSpace Sim block somewhere near line 509 (put it as the last xxxxSet entry)

[b]
      DeclareNamedSet(twSurfaceSet)  //(Note: no semi-colon)
[/b]

6. Open /engine/console/simBase.cc
and add the following line in the nameSpace Sim block somewhere near line 19 (put it as the last xxxxSet entry)

[b]
      ImplementNamedSet(twSurfaceSet) //(Note: no semi-colon)
[/b]

7. Open /engine/console/simManager.cc
and add the following line in function void init() somewhere near line 269 (put it as the last xxxxSet entry)

[b]
      InstantiateNamedSet(twSurfaceSet);  // Now there IS a semi-colon
[/b]

8. Do a clean build of your project.


Script Integration changes
---------------------

9. Open /example/common/editor/ObjectBuilderGui.gui
(somewhere near line 460, after // Environment )

and add this function:

[b]
      function ObjectBuilderGui::buildtwSurfaceReference(%this)
      {
      	%this.className = "twSurfaceReference";
      	%this.process();
      }
[/b]

10. Open /example/common/editor/EditorGui.cs
(in function Creator::init( %this ) where 'n' is the next number in the sequence
of array assignments)

[b]
         %Environment_Item[n] = "twSurfaceReference";
[/b]

11. Open /example/common/client/missionDownload.cs
In function clientCmdMissionStartPhase3(%seq,%missionName) somewhere near line 65
of array assignments)

AFTER

[i]
         onPhase2Complete();
[/i]

add this line BEFORE any other Start*(); function calls:

[b]
	      StartSurfaceReferencer();
[/b]

Using in a mission file
=======================

12. Add to your mission like any other object. Examples of a twSurfaceRefence mission
object and a modified fxGrassReplicator object are contained in the file 'samples.txt'
in the twSurfaceReference.zip file.

13. Set up your reference surface:

Place the SurfaceReference object over the precise surface that you want to
reference later for your grass. Select a type from the SurfaceType drop-down menu.

14. Place your grass:

14a. Place a modified fxGrassReplicator object in an appropriate location. Make sure that there
is some surface texture the same as you referenced in step 13 above. Select the same
SurfaceType from the drop down menu. Hit 'Apply'.

14b. To make sure your grass does NOT appear on a given referenced surface, then check the
'SurfaceExclusionMode' box. Hit 'Apply'.



NOTES:

- In regular placement mode, the twSurfaceReference looks for texture alphas that are EXACTLY the same for the given type in both the referencer and the grass object at time of placement.

- In exclusion mode, the twSurfaceReference looks for texture alphas that are COMPLETELY different for the given type in both the referencer and the grass object at time of placement.

- The function 'GetTerrainTextures' is an adaptation of code written by James Holmes for his Terrain Path Following add-on.

- the screenshot (small as it is) shows twSurfaceReference being used by fxGrassReplicator, fxFoliageReplicator, AND fxShapeReplicator: a tree-line road (shapes), several hedge-lines (shapes, grass and foliage) and a few copses and spinneys of trees.


[edit]:fixed the incorrect function reference in the instructions at step 3d. should be CreateGrass and not the other.
[edit]:fixed typo in the file name in step 10.
[edit]:added omitted step 4c.
[edit]:added missing semicolon in step 7.