The rolling stock library is loaded dynamically and custom rolling stocks can be added to the 'r_stocks/' folder.
This document describes how to add a custom rolling 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.
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.
Some general guidelines are:
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 can be drawn before initializing to since their rotation axes are needed to do so.
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.
After the rolling stock is initialized you'll automatically be asked if you also want to save it to the library.
After a rolling stock is added to the library it can with ease be placed in any model. Several rolling stocks can be saved and placed as one.
Select one or more connected rolling stocks in the model, right click and choose 'Save Rolling Stock(s) to Library'. This will open up a dialog where you can enter rolling stock information. The plugin will suggest an ID for the rolling stock but you can change it manually. 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 plugin's 'r_stock/' folder to add advanced features such as mechanical 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.
For technical reasons the auto-generated image is somewhat shitty. To get a better preview image open the rolling stock's model in the 'r_stock/' folder and run Ene_Railroad.save_preview_image_rs in the console.
This can also be done after editing the model.
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 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 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 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.
| 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 | |
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 the 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.
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.
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.
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.
The whole folder for the rolling stock can easily be compressed, shared, and decompressed in someone else's rolling stock folder.