Automatically loading trees, Version 2.0
January 24, 2007.

By Dirk Mittler
Email mdirk@sympatico.ca

This suggested C-Script tool should be used with CREDIT given to its author, because its nature implies a more serious type of game-development. Its function is to create a large, specified number of Sprite trees within the confines of a specified target Entity, preferably a Map Entity with or without a Terrain.

Since these trees are scripted, only very simple trees are allowed for now, that consist of a Sprite 'pinned' together, with a copy at 90 degrees to the first Sprite, intersecting along an axis at right-angles to the ground. This way, a possible 200 trees or more wouldn't need to be placed by hand.

One of the principals behind this Script, is that a random x and y coordinate are generated, and starting from a maximum altitude, a c_trace() is performed down to a minimum altitude. Th exact elevation of the surface first struck (such as a Terrain) is measured, as well as the colour of the Texture at that point. This colour is compared to that for the tree, and if they match closely enough, the tree is placed. Otherwise, the number of successfully created trees is not incremented, and the effort continues to find suitable positions.

One fact that I observed with Engine version A6.31 ,  was that although the Function of the created Entity is executed immediately (to allow temporary variables to be passed to just one,) once that Entity's Function hits a wait() instruction, execution may or may not go back up the Stack to where the creating Entity left off. This is possible, because the first time a Function hits a wait() instruction, a new Thread is created for it. Threads share the same Data Segment and Code Segment, but each receives their own copy of the Stack, on which certain important local data is stored. But then execution may resume with the calling Function anyway, due to the fact that it also has an up-to-date Stack Segment of its own.

This can be good, because it allows for potentially more than 1 Entity to be created by the Script, in 1 Frame Cycle. Yet, with A6.31 my experience was that trying to create more than 100 Entities in 1 Frame Cycle created problems.

So my Script tries to create 10 trees at a time, to wait(1), and then to create 10 more trees. With luck and a sustained 25 FPS, 250 trees would then take 1 second to create.

But my code may find your Sprite Images or the Terrain diffuclt to match, for which reason many attemps to set the tree down will logically fail. I've provided code which limits the number of such failures, in which case more than 25 Frame Cycles will be needed to create 250 trees. Yet my code will continue to keep trying, until at least the specified number of each kind of tree has been created. Without bogging the CPU with more than 109 c_trace() calls per Frame Cycle.

One might think it best, to pre-define a simpler colour vector which the Terrain colour should approach, but my code actually samples the Sprite Image for each tree, to obtain this average for the Sprite. This means that an additional 3 BMAPs load, which should still require less memory than the many Entities suggested here. But then the effort gets made, to place each of 3 types of trees according to their own colour, without more needed work.

Yet Image and Terrains could be fed to my code, which simply can't work. In many cases, increasing the tolerance variable will fix that for poorer-quality Images. Finally, if no trees can be placed in practice, my code never exits, but also keeps trying with 100 c_trace() calls per Frame Cycle.

So it would still be best to stick with good Images. And maybe to give me a shout if the code still won't work, and if you feel that it might be useful to you.

-Dirk
