The Track.FreeObj command in CSV routes (or @freeobj in RW routes) allows for rotation in the XZ-plane ("along the Y-axis"), commonly called Yaw. There are various occasions where you would want Pitch (YZ-plane) and Roll (XY-place), too.

I suggest to extend the FreeObj command into the following syntax:

Code: Select all

Track.FreeObj Index; IdxStType; X; Y; Yaw; Pitch; Roll

Index is the rail index to place the object relative to.
IdxStType is the free object index as loaded via Structure.FreeObj.
X is the offset along the X-axis in track coordinates. Negative values shift to the left, positive ones to the right.
Y is the offset along the Y-axis in track coordinates. Negative values shift down, positive ones up.
Yaw is the angle to rotate the object in the XZ-plane. When we look at the object from above it, negative values rotate counter-clock-wise, positive ones rotate clock-wise. The angle is measured in degrees.
Pitch is the angle to rotate the object in the YZ-plane. When we look at the object from the left, negative values rotate counter-clock-wise, positive ones rotate clock-wise. The angle is measured in degrees.
Roll is the angle to rotate the object in the XY-plane. When stand in front of the object and look at it, negative values rotate counter-clock-wise, positive ones rotate clock-wise. The angle is measured in degrees.

Here is an illustration:


Applications:
If you want to randomize the direction individual trees are facing at, it looks more realistic if they are banked a little (using Pitch for back-forward rotation and Roll for left-right rotation).
If you want to place static trains in curves which employ cant, you can roll the train to match the cant.
If you want to place signs that are not always perpendicular to the ground, you can angle them.
Etc...

For the release of version 0.8 (around 2008-07-31), this command is scheduled to be implemented. If there are any things to consider, please discuss them as soon as possible.

Spot on Michelle! This will be a welcome addition to the developers' arsenal!
Alan.

This extension has been implemented as of 2008-07-28.

The extended Track.FreeObj command will become available with version 0.8.

A compatibility may or may not exist exists with route files using the original number of parameters followed by comments on the same line, such as

Code: Select all

.FreeObj 0; 112; 1.65; 0.3; 0; This is a comment

gives a "Pitch is invalid"... error. These kind of in-line comments are used in some routes, but I'm not sure if they should be considered valid BVE code or not.

In Mr. Mackoy's own code, in-line comments are separated from previous statement by a comma, such as

Code: Select all

.FreeObj 0; 112; 1.65; 0.3; 0; , ; This is a comment

which does not generate any error in OpenBVE.

According to mackoy's specification, the CSV file consists of comma-separated statements ("ステートメント (構文) を区切ります。改行と同じ役割をします。"). If a statement starts with a semicolon, it is treated as a comment ("ステートメントが ";" から始まる場合、注釈文になり無視されます。"). Thus, in your first example, the phrase "this is a comment" is not a comment, but is the 6th argument to the FreeObj command, simply because the statement starts with FreeObj. Only in your second example is "This is a comment" actually a comment, because the statement starts with a semicolon (ignoring white spaces).

To illustrate the difference:
Statement1, Statement2, ..., StatementN

where each of the StatementI can be of any of the following formats:
Command arg1; arg2; arg3; ...; argN
; Comment