BBoxEdit for MSTS
April 04, 2002 version 1.2
Copyright 2001,2002 by Robert K. Guy

This is a Bounding_Box editor for MSTS cars and engines.

What's New
__________
V1.2 fixes a logic error and now allows saving files with
out-of-range values.  Use same instructions as below - this
version replaces previous versions - please overwrite the old
versions if present.
V1.1 now properly handles comments.  Commented lines are detected
by the block keywords 'comment', 'skip' or '_' and any text
with the first character '#'.  This version replaces V1.0 and
the old version should just be overwritten with this version.
A comment on the same line as one of the four lines being examined will be
discarded if changes are made and saved.  For example, this line:
	Size ( 3 5 10 ) comment ( Size ( 3.1 5.5 9.9 ) )
when any changes are made to the file will be changed to:
	Size ( 3 5 10 )
even if no changes were made to this line.  See the next section
to find out what four lines are examined.  To preserve a comment
simply open the file with WordPad and place the comments on a
separate line before using BBoxEdit to change any values.

There is one remaining problem involving the <filename>.sd file.
The 'ESD_Bounding_Box' entry is usually the last line of the
<filename>.sd file and can be followed by the closing parenthesis
on the same line.  The closing parenthesis should be placed on
the next line instead.  For example:


BBoxEdit expects the closing parenthesis on a separate line.
____________________________________________________________
shape ( JP130000Cab.s
	ESD_Detail_Level ( 0 )
	ESD_Software_DLev ( 2 )
	ESD_Alternative_Texture ( 0 )
	ESD_Bounding_Box ( -1.45475 0.25306 -9.92918 1.45196 3.75 9.92082 )
)

This is correct but will cause BBoxEdit to produce a bad output.
________________________________________________________________
shape ( JP130000Cab.s
	ESD_Detail_Level ( 0 )
	ESD_Software_DLev ( 2 )
	ESD_Alternative_Texture ( 0 )
	ESD_Bounding_Box ( -1.45475 0.25306 -9.92918 1.45196 3.75 9.92082 ))

Note that in the second example above that the closing parenthesis is on
the 'ESD_Bounding_Box' line.  To correct this error before using BBoxEdit
simply edit the file and put a return (newline) before the final parenthesis
so that the final line has a single parenthesis on it.

BBoxEdit will incorrectly discard the closing parenthesis if the file edited
is in the format of the second example above.  TrainSim will detect the resulting
<filename>.sd file as an error.  To repair the <filename>.sd file simply open the
file for editing and add a final line with just a closing parenthesis on it.


WHAT IS A Bounding Box
______________________
The Bounding_Box is a box shape that determines what portion of the
car is solid.  The portions of the car inside the box will collide
with other solid objects in the world.  These objects include buildings,
bridges, overhead objects, objects alongside the tracks, other cars
and the ground itself.  An improperly defined bounding box will cause
a car to derail too easily and too often.  A common symptom is the
'bouncing' car.  This can be the result of a too large bounding_box
causing the car to collide with the ground and/or other cars.

BBoxEdit will display and allow editing of the following variables
found in .eng, .wag and .sd files:
    Size ( x y z )
    InertiaTensor ( Box ( x y z ) )
    CentreOfGravity ( x y z )
    ESD_Bounding_Box ( x y z xx yy zz )

BBoxEdit attempts to validate the correctness of the various
values and will display out-of-range values in red text.  BBoxEdit
does not change any of the files unless explicitly commanded to do so.
The files can be saved with out-of-range values and a warning will be given.
The files can not be saved if an invalid entry is present.
BBoxEdit will only open files with an extension of .eng or .wag - any other
type of file will display an error.


BACKUP FILES
____________
Backup files are always created for any changed file.  The backup files
can be used to restore the files but this must be done manually
in Windows Explorer.  BBoxEdit will not open any file with an extension
of .bak even if it is a valid backup file.  The extension must be changed
to .eng of .bak in order to open it.


BACKUP FILE NAMES
_________________
BBoxEdit creates a backup file if that file was saved.
Loading a .eng or .wag (car) file also loads the corresponding .sd (shape) file.
BBoxEdit may change either the car file or the shape file or both.
Pressing the 'Save' button results in saving only the files that were
actually changed.  The backup name is composed of the full name of the original
file + an optional number + a .bak extension.

Suppose the original name is 'MyEngine.eng' and the shape file is 'MyEngine.sd'

the first  backup name is 'MyEngine.eng.bak' and 'MyEngine.sd.bak'
the second backup name is 'MyEngine.eng.1.bak' and 'MyEngine.sd.1.bak'
the third  backup name is 'MyEngine.eng.2.bak' and 'MyEngine.sd.2.bak'
the fourth backup name is 'MyEngine.eng.3.bak' and 'MyEngine.sd.3.bak'

and so on.

Because only the file that was changed is saved there will not be pairs of files.
If only 'MyEngine.eng.bak' is present then the shape file was not changed and
a backup was not created.  When creating backups, BBoxEdit will sequentially
number files with respect to the presence of either car file backups or
shape file backups.  If any '.bak' file is present the next backup names will
be set to <filename>.1.bak and if any '.1.bak' file name is present the backup
names will be set to <filename>.2.bak and so on.


RESTORING BACKUP FILES
______________________
Delete the file you don't want and rename the backup by removing the tail of the
filename to restore with the '.bak' extension (including the period).  If the
extension has an optional number remove that also (including the period).

Ex: to restore 'MyEngine.eng.2.bak' rename it to 'MyEngine.eng'

It is tricky to describe how to determine which backup file belongs
to which shape file.  When the files are not in pairs, the next lower
backup pairs with the file in question.  If no lower backup exists then
the current file is to be used.  A useful trick is to go by the date and
time of the file.  CAUTION: Don't delete the current file
unless you're sure you have a backup to restore.

To determine which shape file belongs to which car file you need to open the
car file (.eng or .wag) with WordPad and look for the line
'Shape ( a filename goes here )' near the top of the file.  The filename entered
there (with an extension of '.sd') is the shape file for that car file.

For example given that:

MyEngine.eng has a shape file of MyEngine.sd
MyWagon.wag has a shape file of MyWagon.sd

and given these files in a folder:

MyEngine.sd.bak
MyEngine.sd.1.bak
MyEngine.sd.2.bak
MyEngine.eng.bak
MyEngine.eng.2.bak

MyWagon.sd.1.bak
MyWagon.sd.2.bak
MyWagon.wag.bak
MyWagon.wag.3.bak

MyEngine.sd
MyWagon.sd
MyEngine.eng
MyWagon.wag

Resulting pairs of files:

MyEngine.eng.bak   and MyEngine.sd.bak
MyEngine.eng.bak   and MyEngine.sd.1.bak
MyEngine.eng.2.bak and MyEngine.sd.2.bak

MyWagon.wag.bak   and MyWagon.sd
MyWagon.wag.bak   and MyWagon.sd.1.bak
MyWagon.wag.bak   and MyWagon.sd.2.bak
MyWagon.wag.3.bak and MyWagon.sd.2.bak

Again it is useful to go by the date and time that the file was created.
If SOME of these backup files are deleted, but not all of them, the
order can become unsynchronized.  It is best to keep the oldest (earliest) backups
until the modifications are completely tested and then delete (all) the later
backups you don't want to keep.


CAUTION CAUTION CAUTION CAUTION
_______________________________
CAUTION: BBoxEdit can and will create files which can render an
engine or wagon unusable.  The user of BBoxEdit must determine
that the changes made are sensible.


RULES used by BBoxEdit
______________________
    X = width (across the tracks)
    Y = height
    Z = length (along the tracks)

Size
    No assumptions can be made based on the Size variables.
    These values are assigned by the creator of the car and
    should be changed with caution.

    Length (Size Z) controls how closely the cars are coupled.
    Length does not include the size of the couplers.
    Length MUST be greater than or equal to Bounding_Box length.
        Size Z >= Box Size Z

    A warning message appears any time an attempt is made to change Size Z.

InertiaTensor
    All three variables SHOULD be less than or equal to Size.

    InertiaTensor X <= Size X
    InertiaTensor Y <= Size Y
    InertiaTensor Z <= Size Z

    These values are used by the physics engine of MSTS and help to
    determine how well (or badly) the car rides.

CentreOfGravity
    The COG entry may be absent, in which case the edit boxes are disabled.
    The CentreOfGravity can be located anywhere, usually the Y value
    (height) will be something more than half the Size Y value.

    A low COG (COG Y < Size Y / 2) will increase the stability of the car.
    A high COG (COG Y > Size Y / 2) will make a car tend to tip over.
    COG X and COG Z are commonly 0 - centered on the car.

    These three values are used by the physics engine of MSTS and help to
    determine how well (or badly) the car rides.

Bounding_Box
    Box Size = Box Upper - Box Lower
    The Box Size edit boxes are read only.  Change the Box Size by
    adjusting the lower and upper values.  None of these values
    need to be centered on 0.

    For Bounding Box X (width):
        Left = a negative value
        Right = a positive value
    For Bounding Box Y (height):
        Ground level = 0
        Top = a positive value
        CAUTION: Box Y should never be less than or equal to 0.
                 This causes collisions with the ground.
                 A minimum value of 0.5m is suggested.
    For Bounding Box Z (length)
        Front = a positive value
        Read = a negative value

    Box Size X (width) should be less than or equal to Size X.
        Box Size X <= Size X
    Box Lower Y should be greater than 0.
        Box Lower Y > 0
    Box Upper Y should be less than or equal to Size Y.
        Box Upper Y <= Size Y
    Box Size Y should be less than or equal to Size Y.
        Box Size Y <= Size Y
    Box Size Z should be less than or equal to Size Z.
        Box Size Z <= Size Z


HOW TO USE BBoxEdit
___________________
Install the program BBoxEdit.exe anywhere you like.  You can, for
example, put the program in the TrainSim\Utils folder.
Create an icon on the desktop or put a shortcut in your Start Menu
to start the program.  Press the 'Open' button, or press the 'Open'
speedbutton, or use 'File|Open' on the menu to open a .eng or .wag
file.  It is best to create an association between .eng and .wag
files and BBoxEdit, you can then run BBoxEdit from Windows Explorer
by double-clicking an .eng or .wag file in a folder.

If you don't know how to do this, look in the Windows Help file
under 'associating file types' - Press the Start button then
click Help and type in 'associating file types'.  I have called my
file types 'TrainSim engine' and 'TrainSim wagon'.  While you're
there you can add an association to WordPad as well.  If you add
more than one association you can right click the file (in Windows
Explorer) for a menu of possible actions for that file.

It is important that when you enter the program name for the
association that you follow the name with a space and "%1" - including
the double quotes.  This allows folder names and file names with
embedded spaces.

For example, if you installed this program in the TrainSim\Utils folder,
the correct text to type in the 'Application used' edit box is
(assuming the default installation folder):

C:\Program Files\Microsoft Games\TrainSim\Utils\BBoxEdit.exe "%1"

including the double quotes.

When used with an association the double-clicked file will load
and the data set will be displayed.  Use the 'Open' button to start
the open dialog box.  This is a standard dialog box to find a folder
containing an engine and/or wagon.  An incomplete or invalid file set
will not open and an error will be displayed.

Once successfully opened any out-of-range values will be displayed
in red text.  Edit the values until you're satisfied with them, the
red text will change to black when the values are within the
parameters per the RULES above.  You can press the 'Fix' button to
automatically correct the InertiaTensor values, the Box Upper Y and
Box Lower Y values.  If the Box Size is out of range you must
adjust the Lower/Upper values - the Box Size is a read-only value.
Any invalid number will result in the display of an error
message and the edit box will be highlighted in red.  BBoxEdit
will NOT save a file set if an invalid number is present.

Press the 'Cancel' button to discard ALL the changes you have made.
The file set will be reloaded with the original data.

The 'Save' button will be enabled if any changes have been made.
It is possible to save the file set even if there are out-of-range
values.  This permits you to set any value to whatever you like
however unreasonable it might be.  This feature will allow you to
create file sets that may make your engine or wagon unusable.
Carefully test your modifications before deleting the backup files.

The 'Display files' speedbutton will present a text listing of the
file set.  The filename of the .sd file is first followed by the
text of the .sd file followed by the filename of the .eng or .wag
file followed by the text of the .eng or .wag file.  This is a
read-only list provided only for reference and it does not change
as you edit the values.  It is sometimes useful to refer to it
to obtain the original values as recorded in the files.  It may
also be used to view the files when there is an obvious error in
the original files.  You can not view this list unless the files
can be loaded - any error serious enough to prevent loading the
files will require hand editing of the file with WordPad.

The 'Help' button does nothing at this time.  Help files are very
time consuming to create - this is what you get for free.  Use this
file for help.

The 'Exit' button will close the program.  If the current loaded
file set has been changed a warning will be given allowing you to
save the files first.


THE NUMBERS
___________
All values are in meters.  If the original source file contains
measurements in feet and inches this program will fail.  Those
measurements must first be manually converted to meters.  Open
the file (.eng or .wag or .sd) with WordPad and find the offending
measurement identified by 'ft' or 'in' following the number.  If
there is no unit of measurement indicated then the measurement is
already in meter units and does not need conversion.

The conversion factors are:
	meters = 0.3048 * feet
	meters = 0.0254 * inch
	
ex: 19ft = 0.3048 * 19 = 5.7912 meters
ex: 12ft+3in = (0.3048 * 12) + (0.0254 * 3) = 3.6576 + 0.0762 = 3.7338 meters

The principal offender is the SD40.eng file and it's descendants.
Once you have converted one SD40 file you can usually cut and paste
the same values to the other SD40 type files.

The numbers used for input and output by BBoxEdit are floating point
format numbers with 15 digits of precision.  The values that can
be used are limited to values falling between -65535 and +65535.
Optional sign characters '-' and '+' may be used as the first
character and an optional decimal point '.' may be used as input.
Leading zero characters are optional for input and there will be
at least one leading zero on output for numbers less than 1 and
greater than 0.

BBoxEdit will not permit invalid characters to be typed in, but
it is possible to type in the sign character in a position other than
the first or to type in two decimal points.  In this case an error
will be detected and the files will not be saved until the error
has been corrected.


THE MENUS AND BUTTONS
_____________________
The menu, the speedbuttons and the dialog buttons perform the same
functions - they are duplicated for ease of use.

The Menu
File|Open - open a file dialog box
File|Save - save a file set, disabled if invalid data
File|Exit - close BBoxEdit
Edit|Undo - discard ALL changes to the current file set
Edit|Display files - presents a (read-only) display of the file set


The Speedbuttons - (in order left to right)
Open - open a file dialog box
Save - save a file set, disabled if invalid data
Undo - discard ALL changes to the current file set
Info - an about dialog box
Display files - presents a (read-only) display of the file set
Help - there is currently no help file.  If you keep the
		'BBoxEdit.txt' file and place it in the same directory
		as the program file 'BBoxEdit.exe' the help button will
		open the 'BBoxEdit.txt' file with notepad.
Exit - close BBoxEdit

The Dialog Buttons - (on the right)
Fix - adjust the data to suggested values per the RULES above
Open - open a file dialog box
Save - save a file set, disabled if invalid data
Cancel - discard ALL changes to the current file set
Exit - close BBoxEdit


NOTES
_____
It is possible that I have misinterpreted the RULES for the
Bounding_Box.  If you have reason to believe that this program
creates bad values, or if the program misbehaves in some way,
you can e-mail me at the address below.  I don't promise to answer
and I don't promise to fix the error but I would like to know about it.
This version (v1.1) was improved as a result of a report from a
user of this program, so it is useful to report any problems or
suggest improvements.

LICENSE
_______
Copyright 2001 Robert K. Guy.

You may not make money with this free version of BBoxEdit in any way
whatsoever but you may freely distribute this program as long as no
charge is applied to that distribution.  You are also free to upload
this program to any other site that does not charge a fee for access
or for downloads.  You may only distribute this program in unmodified
form including the complete contents of this archive.

You MUST contact the author regarding commercial distribution of BBoxEdit.
Any such distribution without prior consent is strictly prohibited.

You are not permitted to modify, translate, reverse engineer, decompile,
disassemble or create derivative works based on BBoxEdit.

DISCLAIMER
The author shall NOT be held responsible for any damages arising from the
use of BBoxEdit. BBoxEdit is provided on an AS IS basis, without
warranty of any kind, including without limitation the warranties of
merchantability, fitness for a particular purpose and non-infringement.
The entire risk as to the quality and performance of BBoxEdit is borne
by you. Should BBoxEdit prove defective, you assume the entire cost of
any service and repair.

This is Freeware.

Robert K. Guy
zbobg@juno.com
