clutterIssues.md

Clutter isn't showing up on my terrain

There are numerous potential causes of clutter not correctly appearing on your terrain. Thus, the first step is to narrow down that list. To assist with this I've written a script, that can be found here. When the main part of the script is running, it will display information about the surface your character is currently standing on and copy that information to your clipboard. So keep in mind that while the script is running it'll be continuously copying to your clipboard until you stop the script, or "pause" the game.

In case you're unfamiliar with how to run a script in the editor, here is a quick guide.

1. Launch Arma 3 with your terrain.
2. Load into Eden editor on your terrain.
3. Place a single unit down in an area you want to troubleshoot your clutter.
4. Press the "Play scenario" button in the bottom right.
5. Tab out of Arma and open the script I linked above in your browser.
6. Select all of it (CTRL + A) and copy it to your clipboard (CTRL + C).
7. Open Arma 3 back up, hit escape, and paste the script (CTRL + V) into the debug console.
8. With the script now in the debug console, hit the "local exec" button.

How to use the script

The script will give you "addActions", which are just scroll wheel options. When you first execute the script in the debug console there will be two options:

1. Start surface debug - this will start a script that will run once every second and will print out some information about the surface your character is currently standing on. If the message formatting is a little hard to read, don't forget to check the information it copies to your clipboard, as that should be more readable.
2. Remove these addActions - this will remove the addActions from your character. In order to get them back you will need to local exec the original script again.

When the debug script is already running you won't see the addActions for Start surface debug or Remove these addActions. Instead, you'll see only one option, which is Stop surface debug. Which does exactly what you'd guess, it stops the looping debug script. Here is an example of what the output might look like. Note the frame number is shown at the top, this is just supposed to be an indicator of whether the script is currently running. Also, it's worth noting that the probability is shown in the clutter class, but in reality it's defined in the probability[] in CfgSurfaceCharacters.

If you see something like the above image then you're probably on the right track. It's worth comparing this output to what you have defined in your original config, to confirm that everything is loaded into game as you intended.

If instead of an image like the above, you saw something like the image shown below, then you're in luck, you've narrowed down your clutter issues drastically, but more on that below.

Getting to the bottom of it

This script uses the surfaceType command to get the surface that is currently under your player. When this command returns Default, that means that the game wasn't able to find a matching files entry for something defined in CfgSurfaces. The only three ways that I've seen people make mistakes in this area is capitalization, having what I'm going to describe as a facepalm moment, or forgetting to create a CfgSurfaces entry for the surface. The first step in solving this issue is to identify what texture you've used for the surface. For the following examples, we're going to assume the textures for this particular surface are yourTag_greenGrass_nopx.paa and yourTag_greenGrass_co.paa.

Capitalization

The files entry in the CfgSurfaces for your surface should be ALL lowercase, even if the names of the texture themselves aren't lowercase.

class CfgSurfaces
{
	class Default;
	class yourtag_greenGrass: Default
	{
		// incorrect
		files = "yourTag_greenGrass_*";
		// more surface properties here
	};
	//more surfaces
};

class CfgSurfaces
{
	class Default;
	class yourtag_greenGrass: Default
	{
		// correct
		files = "yourtag_greengrass_*";
		// more surface properties here
	};
	//more surfaces
};

Facepalm

We've all done it, you swear there is nothing wrong with the config and that you've checked dozens of times. Can you spot the error?

class CfgSurfaces
{
	class Default;
	class yourtag_greenGrass: Default
	{
		files = "yourtag_grassgreen_*";
		// more surface properties here
	};
	//more surfaces
};

Hopefully you caught it, files = "yourtag_grassgreen_*" should be files = "yourtag_greengrass_*".

Missing CfgSurfaces entry for the surface

Even if you don't want a surface to have clutter, it still needs an entry in CfgSurfaces, otherwise it won't receive basic properties defined in CfgSurfaces. i.e. sound, correct bullet impact effect, dust, etc. If you take a list of the textures you've used on your terrain, then use a text editor to search (CTRL + F) through your config containing CfgSurfaces, you should find an entry for each texture. This is assuming that you chop the co or nopx of the end of the texture for the purpose of searching for matching files entries.