AddObjects

AddObjects is a tool that allows you to place large numbers of custom objects into an .env scenery file. Since custom scenery packages cannot use autogen scenery, AddObjects provides an alternative: a fast way to place objects based on terrain textures.

AddObjects adds objects to an .env file. Once they are added, you can drag and drop them in WorldMaker, delete them, move them slightly, etc. While AddObjects tends to make algorithmic object patterns, you can then customize the objects any way you want once they are placed.

Using AddObjects

To use AddObjects, drag an .env file and one or more .opf (Object Placement File) files into the AddObjects window all in one drag. A new .env file, with _new suffixed on its name, will be created. This new env file has all of the contents of the old env file plus new placed objects.

Writing Object Placement Files

Object placement files are text files that allow you to specify the placement of objects on a scenery quad. A quad is one square within a .env file; there are 30,000 quads in a single .env file. Each quad may have its own land use or custom texture.

Each .opf file specifies objects to be added to a quad that has a custom texture of the same name. So if you have a custom texture called "urban_commercial1.bmp" and you want to place objects on all uses of it, create an .opf file called "urban_commercial1.opf". You can use multiple .opf files with AddObjects to modify many terrain types, but you may only have one .opf file per each custom terrain texture.

.opf files have instructions for object placements, blank lines, or lines starting with a # for a comment. The following commands are supported:

The OBJECT Command

The object command is the fundamental command for placing an object. When AddObject encounters an object command, it places a custom object into the file. The format of the object command is:

OBJECT <lon_west> <lon_east> <lat_south> <lat_north> <min_heading> <max_heading> <chance> <name>

For example:

OBJECT 0.1 0.5 0.6 0.6 0 90 0.5 city:house

Here is what the fields mean:

lon_west, lon_east. These numbers define the range within the quad that the object can appear as a ratio; 0.0 indicates the west edge of the quad and 1.0 indicates the east. In this case the object can appear anywhere from 10% right of the left edge of the quad to half way across the quad. All positions are specified as fractions of a quad so that if the quad is stretched, the objects move to align with the pixels of the texture they are placed upon. Make these numbers be the same to place an object at an exact location, or specify a spread for random placement.

lat_south, lat_north. These numbers define the range north-south that the object may appear in. In the above example, the object will always appear 60% of the way from the south to the north edge of the quad.

heading_min, heading_max. These numbers specify the range of headings the object might face in, from 0 to 359 degrees. This object may face anywhere from north to east.

chance. This defines the percentage of the time that the object will be placed on this texture. In this case, the object is placed half the time. 1.0 means place all the time, 0.0 means never place the object.

name. This is the name of the object file, including relative path, but excluding the .obj extension.

Any parameter may be randomized or kept constant (by having the min and max be the same). Names are affected by the alias command (see below).

The ALIAS Command

The alias command lets you automatically substitute other objects for one object randomly, or even have the object not be placed. The format of the alias command is:

ALIAS <object name> <object 1> <chance 1> <object 2> <chance 2> ... <object N> < chance N>

For example:

ALIAS house red_brick_house 0.3 blue_shack 0.1 apartment_building 0.6

You may specify as few or as many objects as you wish. When ObjectMaker finds an OBJECT command with the alias specified on the left, one of the objects on the right will be used based on the percentages specified. In the above example, 30% of the time a red brick house will be applied, 10% of the time a blue shack, and 60% of the time an apartment building. If the percentages do not add up to 1.0, the remainder of the specified time will be treated as 'do not place this object'.

The GROUP Command

The group command lets you specify a number of other commands that must all be used together or not be used together. For example, let's say you have a quad that can contain four apartment buildings forming a complex. You want to assure that the buildings either all show up or none show up. The group does this. The format is:

GROUP <chance>

For example:

GROUP 0.5
OBJECT 0.1 0.1 0.5 0.5 0 0 1.0 house
OBJECT 0.1 0.1 0.6 0.6 50 50 1.0 swimming_pool
END

All commands that follow the group until the next END will be executed some percent of the time, based on chance. For example, any objects following this group will appear half the time. If those objects have a chance of 1.0, then all of those objects will appear at once half the time, and none will appear half the time.

The END Command

The end command specifies the end of a group. The format is:

END

Groups can be nested; you will need an END command for each group command.

The SWITCH Command

The switch command gaurantees mutual exclusivity. Normally objects are added some percent of the time independently. For example, if there are two objects in a row, each with a chance of 0.5, then 25% of the time none will be added, 25% of the time both will, 25% of the time the first will but not the second, and 25% of the time the second will but not the first; all decisions are independent.

Inside a switch command, only one of the following commands will be executed, based on its chance. The format of a switch command is:

SWITCH

For example:


SWITCH
OBJECT 0.5 0.5 0.5 0.5 0 0 0.3 hospital
GROUP 0.7
OBJECT 0.1 0.1 0.5 0.5 0 0 1.0 house
OBJECT 0.1 0.1 0.6 0.6 50 50 0.5 swimming_pool
END
END

In this example, the hospital and the group are mutually exclusive. 30% of the time, a hospital will appear. 70% of the time, a house will appear. And when a house appears, only 50% of the time will it have a swimming pool.

A few key concepts are illustrated with this example:

The chance for a group or object is independent when inside a group command (or just in the .opf file), but dependent when in a switch command. In this case, the house and swimming pool chances are independent beacuse they are in a group, while the group and hopsital chances are dependent because they are in a switch.
Groups and switches can be nested. In this case, a group will either be entirely taken or not taken based on a switch.
Nested groups or switches have layers of probability. In this case, the swimming pool will appear 35% of the time: its group appears 70% of the time, but then when the group appears, it appears only 50% of the time.

Using Austin's Autogen Commands

You can use all of Austin's autogen commands except for the RAN (random) command. Use the SWITCH command instead of RAN.

Important: the purpose of providing support for Austin's commands in AddObjects is to allow authors who have created autogen text files to rapidly convert their autogen definitions into large sets of objects. When you use these commands you must provide custom object files (.obj files) in your scenery package for each type of tree, light and forest you use. AddObjects will make up a name for these objects that you must match. (One easy way to confirm the names AddObjects uses is to run the whole file through Env2CSV; the last few lines are the list of custom objects in the file.)

When you use the LIT (light), FOR (forest), or TRE (tree) commands, AddObjects places a custom object with a specific name. You must provide this object using an .obj file to see these lights, forests, trees, etc. This allows you to customize the way these objects look. Austin's default tree is two vertical quads forming a plus shape (with side views of a tree as the texture). His forest is five stacked horizontal quads with cross sections of a forest. His light object is one point light a few meters above the ground. The naming conventions for the objects work as follows:

When you use the TRE command, you specify a numeric type. The custom object's name will then be:

DEF_TRE_<type>.obj

for example:

TRE  0.50 0.50 0.40 1.00      3

would require:

DEF_TRE_3.obj

When you use the FOR command, you also specify a numeric tpye. The custom object's name will then be:

DEF_FOR_<type>.obj

for example:

FOR 0.50 0.50 0.40 1.00        4

would require:

DEF_FOR_4.obj

When you use the LIT command, you specify an RGB color and elevation. The custom object's name will then be:

DEF_LIT_<elev>_<r>_<b>_<g>.obj

For example:

LIT  0.05 0.50 0.01 1.00     8.0 10  8  4

would require the object

DEF_LIT_8_10_8_4.obj