From TDN

This page is a Work In Progress.

Contents 1 Introduction 2 fxfoliageReplicator 3 Known Limitations

Introduction

The fxfoliageReplicator allows you to easily place billboards across your mission.

fxfoliageReplicator

By creating billboards, this datablock helps place sprites of grass and foliage in abundance throughout your level. Please also check out this tutorial Building Better Foliage.

An example fxShapeReplicator for grass:

new fxFoliageReplicator(grass) {
      position = "384.338 102.238 360.714";
      rotation = "1 0 0 0";
      scale = "1 1 1";
      UseDebugInfo = "0";
      DebugBoxHeight = "1";
      HideFoliage = "0";
      ShowPlacementArea = "1";
      PlacementAreaHeight = "25";
      PlacementColour = "0.4 0 0.8 1";
      Seed = "1129375053";
      FoliageFile = "~/data/textures/decals2/fern.png";
      FoliageCount = "13000";
      FoliageRetries = "50";
      InnerRadiusX = "0";
      InnerRadiusY = "0";
      OuterRadiusX = "128";
      OuterRadiusY = "128";
      MinWidth = "1";
      MaxWidth = "3";
      MinHeight = "1";
      MaxHeight = "3";
      FixAspectRatio = "1";
      FixSizeToMax = "0";
      OffsetZ = "0.5";
      RandomFlip = "1";
      UseCulling = "1";
      CullResolution = "64";
      ViewDistance = "50";
      ViewClosest = "1";
      FadeInRegion = "10";
      FadeOutRegion = "1";
      AlphaCutoff = "0.8";
      GroundAlpha = "0.9";
      SwayOn = "1";
      SwaySync = "0";
      SwayMagSide = "0.1";
      SwayMagFront = "0.2";
      MinSwayTime = "3";
      MaxSwayTime = "10";
      LightOn = "1";
      LightSync = "0";
      MinLuminance = "0.7";
      MaxLuminance = "1";
      LightTime = "5";
      AllowOnTerrain = "1";
      AllowOnInteriors = "0";
      AllowOnStatics = "0";
      AllowOnWater = "0";
      AllowWaterSurface = "0";
      AllowedTerrainSlope = "90";
   };

The fields can be a pain to figure out without breaking something, so here's a description from Melv May's (the author) readme file:

---

The fxFoliageReplicator offers many options to allow you to create fairly realistic random placement.

The following options are available:-

Seed This value is the Seed value for the random number generator. Changing this value results in a different distribution of pseudo-random numbers. You can change this value to almost anything if you are not happy with the placement of objects that has been choosen. Also, if you populate with multiple replicators then give each a different number. Note that a small value change here results in a completely different set of placements.

FoliageFile This allows you to select any texture file. Valid paths include the mod directory, so something like "fps/data/mycoolgrass1" would do fine. Sorry, no compound textures at the moment but that is coming. For the moment, simply use multiple replicator objects.

FoliageCount The quantity of replicated Foliage items you require. Make sure your graphics card can handle it or you'll end up with 1fps (or less!)

FoliageRetries When the replicator is tasked with finding a home for each Foliage item, it will look at the configuration options described within the replicator and attempt to find a random position to place it. It will choose random locations and then see if they fit the configuration constraints, if not then it will try again. The replicator will attempt this <FoliageRetries> for EACH object. If it does not succeed then it will give up for that object and continue with the next.

RadiusInnerX/Y The placement area for billboards is centered around the replicator position based upon an elliptical ring-area whose inner bound is defined with <RadiusInnerX,RadiusInnerY>. The replicator will choose a random polar angle outside this region.

RadiusOuterX/Y The placement area for billboards is centered around the replicator position based upon an elliptical ring-area whose outer bound is defined with <RadiusOuterX,RadiusOuterY>. The replicator will choose a random polar angle inside this region.

Min/Max Width/Height Each foliage object will be created with a random width and height between these max and min values.

OffsetZ When placing foliage on the terrain, sometimes they do not quite meet the ground. Also, when placed on steep terrain, the bottom of the texture often sticks out above the terrain when viewed from certain angles. Use -Z values to lower Foliage and +Z to raise them.

RandomFlip Randomly flips the the billboard horizontally. This can add a little more variety to the billboard images. Obviously this is only effective on non-horizontally-symmetric textures.

---

UseCulling Turns-on the culling facility. If you are using the replicator to create only a few items or only in a very small area them the culling algorithm can actually slow things down slightly. This gives you the ability to turn it off although you should avoid this unless you are sure you know what you're doing!

CullResolution The culling algorithm is difficult to explain but it is essential to understanding how to efficiently control large quantities of billboards. Without culling *all* billboards are tested to see if they are in view and if so they are rendered. If your billboards are spread out over a large distance then chances are that you won't be able to view many of them but they are still tested to see if they are in view. The culling algorithm avoids this and only tests the ones that are in view. How can it know this without testing them, chicken and the egg I hear you shout! Well, the replicator creates a structured database of billboards and their positions at the level startup phases. Basically the algorithm splits up your total defined area (see 'RadiusOuterX/Y') into quadrants the smallests of which is this field 'CullResolution'. Above these are progressively larger blocks which cover each lower quadrant. Imagine a cube of blocks where each block has four smaller blocks directly below it repreating for many levels until each small block is your resolution. Teh algorithm can check the larger block first and check to see if it's in view. If it's not it can effectively ignore all the smaller sub-areas below it therefore removing the need to check them. I told you this was difficult to explain!

Basically, the rule is that the replicator will split up the replicated area into blocks the size of 'CullResolution'. The larger your area, the more time and memory are needed to create this structure. Try to keep the 'CullResolution' large enough so that good-size blocks of foliage can be checked quickly but not too large that the blocks are as big as your viewing frustum. Also, your viewing frustum is not simply the 'VisibleDistance' as set in the "Sky" object but the smaller of that or the 'ViewDistance'+'FadeInRegion' as set in this object.

As an example:-

The 'VisibleDistance' is 500, The 'RadiusOuterX/Y' are 512 (an area 1024 squared), The 'ViewDistance' is 250 and the 'FadeInRegion' is '50'.

A good setting fr this scene would be 64 as the area is quite large (1024 squared) and results in 1024/64 highest resolution blocks.

---

ViewDistance Controls the point at which the foliage will be completely faded-in.

ViewClosest Controls the point nearest to the camera at which the foliage will start fading-out. This can be use to stop foliage entering the cabin when a vehicle like the Racing demo.

FadeInRegion>/<FadeOutRegion Controls the distances which the fade-in/out will take place. A larger value will result in a slower/longer fade-in/out. The FadeIn/Out extend the ViewDistance/ViewCloset parameters.

AlphaCutoff Allows you to control the alpha level at which the rendering takes place. This can be very handy in feathering the edges of the foliage.

GroundAlpha Allows you to control the alpha level at the base of the billboard. This allows you to reduce the harsh intersection that billboards have with the terrain.

SwayOn Turns the animated swaying on/off - Duh!

SwaySync Ensures that all the billboards sway in sync (within each replicator).

SwayMagSide>/<SwayMagFront The distance of the swaying side to side and front to back respectively.

MinSwayTime>/<MaxSwayTime The limits of a random period for the swing (in seconds).

LightOn Turns the animated luminance on/off - Duh!

LightSync Ensures that all the billboards are lit in sync (within each replicator).

MinLuminance>/<MaxLuminance The limits of the luminance shift (0 - 1).

LightTime The time taken to sweep from Min->Max->Min luminance values.

AllowedTerrainSlope When placing objects onto the terrain (or other objects - see 'AllowStacking') the replicator will ensure that it meets the slope requirements. You can control the maximum slope (from the 'Up' vector 'Z' in degrees). 90 degrees gives almost no restriction but something like 15 degrees only allows objects to be placed on fairly flat terrain.

HideFolliage This option allows you to temporary hide the replicated objects. This could be handy if the replicated objects are obscuring some detail you are editing. For instance, you may be hiding a secret key in the forest ... :)

---

Known Limitations

• If the number of objects is set to zero or a very large number (over 30,000 or so) then the fxFoliageReplicator will crash (with zero plants) or lock up the game (with large numbers).
• If the RadiusOuterX/Y values are extremely large (5-6000 units) the system performance in editor mode can deteriorate because of the large amount of drawing necessary to draw such a large circle.