# Creating Rolling Stock

The rolling stock library is loaded dynamically and custom ones can be added to the rolling stock directory. To open this directory run: EneRailroad::Template.open_dir(:r_stock).

There can be multiple (actual) rolling stocks in what's listed as one rolling stock in the library, such as a steam locomotive along with its tender.

Although rolling stocks are saved similar to other templates the process to do so is slightly different. There's a graphical user interface to set the rotation points and buffer distances for rolling stocks. This is because it would be somewhat complicated to manually edit the attributes for many users and because rolling stocks probably are customized more than the other customizable content.

## Drawing the Group

A rolling stock must be drawn as a group. It cannot be a component since the plugin may alter it when driving, e.g. turn bogies and rotate wheel axes. However it can contain components for geometry that occurs more than once.

This group can be drawn in any model, e.g. on a track to get the wheel position right.

Some general guidelines are:

- Use a component for each half if the rolling stock that has one symmetry plane
- Use a component for each quarter if the rolling stock that has two symmetry planes
- Place these parts in the rolling stock root rather than in nested groups/components:
  - Bogies
  - Mechanical (moving) parts
  - Tilting car body
  - Text signs
  - Lights

These parts are dynamically changed by the plugin and are easiest to draw once the rolling stock is initialized since they can then be tested more easily. The exception is the bogies which is easier o draw before initializing to since their rotation axes are needed to do so.

## Initialize

Select the rolling stock group, activate the Add Rolling Stock tool and follow the instructions in the dialog. It can be helpful to place the rolling stock group on a track before trying to find the required points.

## Add to Library

After the rolling stock is initialized you'll automatically be asked if you also want to save it to the library. You can at any time select a group for an initialized rolling stock, right click and save it to library. You can also draw and initialize several separate rolling stocks, connect them using the Coupling tool, select them, right click and save them as one rolling stock in the library, e.g. a steam locomotive along with its tender.

The plugin will suggest an ID for the rolling stock but you can change it manually. The ID should start with a prefix for the user creating the rolling stock to avoid name collisions and files accidentally being overwritten. If you are a plugin author and are already using a unique prefix for plugins you can use the same prefix for your rolling stocks. The prefix will be saved on the computer and suggested the next time you save a rolling stock.

Once the rolling stock is added to the library you can open its model from the rolling stock directory, similar to how other content is customized, to add advanced features such as moving parts. Meanwhile you can have another SU session opened where you periodically place the updated rolling stock from the library to test that it all works.

## Update Information

To update the information, e.g. the name, run EneRailroad::Template.edit_properties in the console when inside the rolling stock template model.

## Update Preview Image

For technical reasons the auto-generated image is somewhat shitty. To get a better preview image open the rolling stock's model in the rolling stock folder and run EneRailroad::Template.cretae_preview in the console.

This can also be done after editing the model.

## Drawing Advanced Content

### Bogies

A rolling stock can have bogies that turns when it goes through a curve.

Each bogie should be placed in the rolling stock root. If it contains mechanical parts it should be a group, otherwise it may be a component. The bogies' internal coordinate axes should be placed (Right click on axes > Place) with the origin where the rotation axis meets the top of rail plane and x axis pointing away from rolling stock center. Z axis should point upwards as usual.

The first bogie in the default direction of travel should be named 'boigie0' and the other 'bogie1'. The first bogie's coordinates should be the same as for the whole rolling stock.

### Mechanical Parts

Mechanical parts are groups or components moving with a predefined motion with a speed relative to the one of rolling stock. This can be used for wheel axes and connecting rods.

To create a mechanical part draw a group or component in model root or inside a bogie and add all required attributes to it. The attributes can be set using Eneroth Attribute Editor which was actually created for just this.

All point and vector attributes should be relative to the rolling stock group or the bogie group the part is located in. These values should be saved as arrays to prevent them from being transformed when the part is moved.

All lengths should be in inches, SU's internal length unit.

#### Available motion types

Rotation
Rotates around internal origin. In start position local axes should match rolling stock axes.
Attribute | Description
motion_type | "rotation"
cycle | The length rolling stock travels before this part is back in its original state.
cycle_offset* | How much ahead this part should be measured in cycles. Default is 0.
rotation_vector* | Vector to rotate around. Default is [0, 1, 0].
*Optional

Circular translation
Translation in internal x-z plane with internal origin rotating around given point. Used for connecting rods.
Attribute | Description
motion_type | "translation_circular"
cycle | The length rolling stock travels before this part is back in its original state.
rotation_point | Point to rotate internal origin around.
radius | distance between rotation_point and internal origin.
cycle_offset* | How much ahead this part should be measured in cycles. Default is 0.
rotation_vector* | Vector to rotate around. Default is [0, 1, 0].
vector_to_start_position* | vector telling what position part should start in. Default is [0, 0, 1] (up).
*Optional

Linear harmonic translation
Moves back and forth along internal x axis.
Attribute | Description
motion_type | "translation_linear_harmonic"
cycle | The length rolling stock travels before this part is back in its original state.
center_point | Point where internal origin is at start.
amplitude | Maximum distance between center_point and internal origin.
cycle_offset* | How much ahead this part should be measured in cycles. Default is 0.
*Optional

Rotation and reciprocation
Internal origin rotates around a point while other end moves back and forth along a line.
Attribute | Description
motion_type | "combined_rotation_reciprocation"
cycle | The length rolling stock travels before this part is back in its original state.
rotation_point | Point to rotate internal origin around.
radius | distance between rotation_point and internal origin.
length | distance from origin in positive x to the point moving linear.
line | Line to move reciprocating end along. Defined as an array of a point and vector.
cycle_offset* | How much ahead this part should be measured in cycles. Default is 0.
rotation_vector* | Vector to rotate around. Default is [0, 1, 0].
vector_to_start_position* | vector telling what position part should start in. Default is [0, 0, 1] (up).
*Optional

Linear reciprocating translation
Internal origin corresponds to the point moving linear in a combined_rotation_reciprocation with similar attributes. All attributes except "motion_type" can be copied from corresponding combined_rotation_reciprocation
Attribute | Description
motion_type | "translation_linear_reciprocation"
cycle | The length rolling stock travels before this part is back in its original state.
rotation_point | From corresponding combined_rotation_reciprocation.
radius | From corresponding combined_rotation_reciprocation.
length | From corresponding combined_rotation_reciprocation.
line | Line to move reciprocating internal origin along. Defined as an array of a point and vector.
cycle_offset* | How much ahead this part should be measured in cycles. Default is 0.
rotation_vector* | Vector to rotate around. Default is [0, 1, 0].
vector_to_start_position* | vector telling what position part should start in. Default is [0, 0, 1] (up).
*Optional

#### Getting the values from model

cycle can be retrieved by selecting the outer circle of a wheel and run Sketchup.active_model.selection[0].curve.length.

Similarly lengths can be retried from edges by selecting them and run Sketchup.active_model.selection[0].length.

To know how to place internal origin and axes for the mechanical parts and get values for attributes temporary help edges can be made. In this example an edge is drawn from the wheel's center point along its axis to the plane of the outermost rod. From here there's an edge to the rods. This edge can be used to get rotation_point, radius, vector_to_start_position and position for internal origins for the rods.

When the mechanical parts on one side are initialized they can be copied and mirrored to the other side of the rolling stock. To prevent the copies from going back to their original positions when train runs, negate the y coordinate of all points and vectors in their attributes.

On steam locomotives there's often a 90° difference between the position of the rods at the different sides. To achieve this set cycle_offset to 0.25 (point as decimal mark) on the parts at one sides.

### Tilting Car Body

A rolling stock can have a part that tilts when going through a curve.

The tilting part should be located in the rolling stock root and be a group if it contains dynamic text, otherwise a component. This group or component should be named 'tilting'.

The tilting part rotates around its internal x axis.

### Text

A rolling stock can have text that can be changed from its context menu, for instance showing its destination or number.

To create a piece of dynamic text, make a group in the model root, or tilting group, containing some random geometry such as a face. Name the group 'text_Label' where Label is what you want to call the text, e.g. text_Number, text_Class or text_Destination. Exit the group, right click the rolling stock and chose 'Change Text' to enter your text.

To use another font, save its name as a string by the key 'font' in the attribute directory 'ene_railroad_text' for the group but be aware that all users may not have your chosen font installed.

### Lights

A rolling stock can have both headlights and tail lights in each end that are shown or hidden depending on the current direction of travel.

The lit lights are drawn in the rolling stock root or tilting group. The lights should be named 'light0_front', 'light1_back', 'light1_front' and/or 'light0_back'. Front/back is from the current direction of travel (front being white and back red). 0 and 1 is from the default direction of travel similar to how bogies are named.

When traveling forwards 'light0_front' and 'light1_back' are shown and the others hidden. When traveling backwards 'light1_front' and 'light0_back' are shown and the others hidden.

The unlit version of the lights is not dynamic and can be drawn just as any other geometry just behind the lit version to be hidden by it when light is lit.

## Distributing rolling stock

The whole folder for the rolling stock can easily be compressed, shared, and decompressed in someone else's rolling stock folder.

Copyright © Julia Christina Eneroth 2015.