RailCar

Rail car type properties
Functions

Rail cars are created by TrainSource blocks within trains and are fully controlled by trains during their whole lifetime in the rail yard.

Rail car animation

The default 2D animation of the rail car is a rectangle. The default 3D animation is a parallelepiped. The color of the default animations can be customized by calling rail car’s setColor(). Usually users create custom rail car types and assign custom animation shapes for rail cars of different types. The 3D Objects palette contains ready-to-use 3D animations for different types of cars and locomotives.

The size of the rail car custom animation will not be automatically adjusted to the length of the car, so you need to choose the proper scale of the animation shape to ensure there are no spaces between cars in the train and cars are not drawn one above the other.

From the Rail Library viewpoint there is no difference between a car and a locomotive or between cargo and passenger car, but you can make such distinction in your model, for example, you can specify different dimensions, assign different animation shapes, or create different rail car types with different properties and functions.

A rail car has length and two sides: front and rear. The length of the rail car can only be set up at the time of its creation (e.g. in the Car length or in the Car setup code of TrainSource) and cannot be changed later on. You can get the location (track, orientation on track, and offset) of the either side of the car. You can ask the car to execute a custom action at the specified point of a given track. Arbitrary information can be passed to the callback code.

Rail cars in 2D

Rail cars in 3D

To create a custom rail car type

Open the Rail Library palette and drag the Rail Car Type element onto the agent type diagram, e.g. Main.
The New agent wizard dialog window will open. Specify the Agent type name. Click Next to proceed to the next step.
Now you can select 3D or 2D animation figure for the car. Select None if you do not need a car animation or if you would like to add your own animation figure later.
Here you can define the parameters of the rail car. Click < add new...> and specify the parameter name, type, and default value. To remove a parameter from the list, click the button . You can always add more parameters onto the rail car diagram after you finish creating it.
Click Finish. AnyLogic will automatically open new rail car type diagram. You can find the animation figure in the axis origin.
Now you can use the new car type in the Rail Library blocks parameters, for instance, in TrainSource properties:

Rail car type properties

General

Name — The name of the rail car type.

Since AnyLogic generates Java class for each rail car type, you should follow Java naming guidelines, and start the name with an uppercase letter.

Ignore — If selected, the rail car type is excluded from the model.

Parameters preview

Parameters preview properties are available only when this rail car type has any parameters. Here you can rearrange parameters of this rail car. Rail cars of this type will list parameters in their property view in this well-defined order.

Agent actions

On startup — Code to be executed after all agents throughout the whole model are constructed, connected, and initialized, and before anything else is done. This is a place for some additional initialization of the rail car. The order of execution of On startup code of different agents is not guaranteed. We recommend to perform rail car initialization not here, but in the Car setup property of the TrainSource block that generates trains in your model.

On destroy — Code to be executed on destroying rail car of this type. This parameter is derived from agent type and is rarely used for rail cars. For details refer to the Agent article.

On arrival to target destination — This parameter is derived from agent type and is not applied to the movement defined with a Rail Library flowchart.

On before step — This parameter is derived from agent type and is rarely used for rail cars. For details refer to the Agent article.

On step — This parameter is derived from agent type and is rarely used for rail cars. For details refer to the Agent article.

Agent in flowcharts

Use in flowcharts as — Here you choose the role for agents of this type in the flowcharts. To enable using these agents as rail cars in the blocks of the Rail Library, leave the Rail car option selected. This way the agent of this type obtains rail car-specific functions: getTrain(), getDistanceDriven(), isFirst(), etc.

On enter flowchart block — Here you can write the code to be executed when this rail car enters the flowchart.

On exit flowchart block — Here you can write the code to be executed when this rail car exits the flowchart.

On seize resource — This parameter is derived from agent type and is rarely used for rail cars.

On release resource — This parameter is derived from agent type and is rarely used for rail cars.

Dimensions and movement

The parameters in this section are derived from agent type and are rarely used for rail cars. For details refer to the Agent article. Define the length of the rail car in the Car length property of the TrainSource block that generates trains in your model.

Space and network

The parameters in this section are derived from agent type and are rarely used for rail cars. For details refer to the Agent article.

Advanced Java

The parameters in this section are derived from agent type and are rarely used for rail cars. For details refer to the Agent article.

Advanced

The parameters in this section are derived from agent type and are rarely used for rail cars. For details refer to the Agent article.

Functions

General API (functions that are always available no matter whether the car is controlled by a Train or not)

Dimensions

Function	Description
double getLength()	Returns the length of the car in meters.
double getLength(LengthUnits units)	Returns the length of the car in the specified length units. units — A constant defining the length units
void setLength(double lengthInMeters)	Sets the length of the car. Can only be done before the car is added to the rail yard. lengthInMeters — The length of the car in meters
void setLength(double length, LengthUnits units)	Sets the length of the car in specified length units. length — The new length of the car units — One of length unit constants
double getWidth()	Returns the width of the car in meters.
double getWidth(LengthUnits units)	Returns the width of the car in specified length units. units — One of length unit constants
void setWidth(double width)	Sets the width of the car in meters. width — The new width of the car in meters
void setWidth(double width, LengthUnits units)	Sets the width of the car in specified length units. width — The new width of the car units — One of length unit constants

Animation

Function	Description
Shape getShape()	Returns a custom shape that is used to animate the car, or null.
void setShape(Shape shape)	Sets a custom 2D or 3D shape that will be used to animate this car.
Color getColor()	Returns the color of the car.
void setColor(Color color)	Sets the color of the car. Although the color is always stored in a RailCar block, it only applies to the default animation. color — The new color
boolean isHighlighted()	Tests if the rail car is currently highlighted. Returns true if highlighted, false otherwise.
void highlight(boolean yes)	Highlights or dehighlights the rail car. yes — true for highlighted status, false for regular

Information about the car

Function	Description
Agent getTrain()	Returns the train the car belongs to, or null.
Agent getCoupledCar(boolean infront)	Returns the car coupled with this one at a given side, or null. infront — If true, this is front side, otherwise rear side
boolean isFirst()	Checks if this if the first car in a sequence of coupled cars (which does not necessarily form a Train block), i.e. if there is no coupled car moving before this car. If the car is not moving, the result is undefined. Returns true if this is the first car in a sequence (or a standalone car), false otherwise.
boolean isLast()	Checks if this if the last car in a sequence of coupled cars (which does not necessarily form a Train block), i.e. if there is no coupled car moving after this car. If the car is not moving, result is undefined. Returns true if this is the last car in a sequence (or a standalone car), false otherwise
RailwayTrack getTrack(boolean infront)	Returns the track on which a given side of car is currently located. infront — If true, this is front side, otherwise rear side
double getX(boolean infront)	Returns the x coordinate of a given side of the car relative to the rail yard group of shapes in pixels. infront — If true, this is front side, otherwise rear side
double getY(boolean infront)	Returns the y coordinate of a given side of the car relative to the rail yard group of shapes in pixels. infront — If true, this is front side, otherwise rear side

Movement control

Function	Description
boolean isMoving()	Tests if the car is currently moving. Returns true if moving, false if not
boolean getDirection()	Returns the direction in which the car is moving (or was moving last time): true if forward (front before rear), false if reverse
boolean getOrientation(boolean infront)	Tests if the car has same orientation as the track on which a given side of the car is located. Returns true if the car has same orientation as the track. infront — If true, this is front side, otherwise rear side
boolean isForwardOnTrack(boolean infront)	Returns the direction of the car movement relative to the track on which one (or both) sides of car are located. Returns true if car direction is same as track (start-end). infront — If true, this is front side, otherwise rear side
double getOffset(boolean infront)	Returns the offset of a given side of car relative to the track start point in meters: 0 — the beginning of the track. infront — If true, this is front side, otherwise rear side
double getOffset(boolean infront, LengthUnits units)	Returns the offset of a given side of car relative to the track start point in specified length units: 0 — the beginning of the track. infront — If true, this is front side, otherwise rear side units — One of length unit constants
double getDistanceDriven()	Returns the distance driven by the rail car in meters since its creation or since the last call of resetDistanceDriven().
void resetDistanceDriven()	Resets the distance driven by the rail car to zero.
double getSpeed()	Returns the speed of the car in meters per second. Nonzero speed does not mean the car is moving.
double getSpeed(SpeedUnits units)	Returns the speed of the car in given speed units. Nonzero speed does not mean the car is moving. units — One of speed unit constants

Miscellaneous

Function	Description
RailwayNetwork getRailYard()	Returns the rail yard where the car is currently in.
RailSettings getSettings()	Returns the settings of the rail yard.

Callbacks

Function	Description
void callbackAt(RailwayTrack track, double offset, Object info)	Requests the rail car to execute a callback (parameter onAtCallback of the RailSettings) at the specified point, namely when its side that moves in front reaches that point. Just before the callback this request is discarded (although in the callback code the user may request another one). Each new request discards a previous one. You can pass arbitrary information (Object) to the callback code to identify what kind of event it is. track — The track to execute callback at offset — Offset on the track to execute callback at (in meters) info — Arbitrary Java object that will be passed to the callback code
void callbackAt(Railway Track track, double offset)	Same as callbackAt(track, offset, null). track — The track to execute callback at offset — Offset on the track to execute callback at, meters
void callbackAt(RailwayTrack track, PositionOnTrack pointOnTrack, Object info)	Same as callbackAt(track, offset, info) where the offset is the offset of intersection of the track and a given position on track. track — The track to execute callback at pointOnTrack — Position on Track info — Arbitrary Java object that will be passed to the callback code element that crosses the track
void callbackAt(RailwayTrack track, PositionOnTrack pointOnTrack)	Same as callbackAt(track, pointOnTrack, null). track — The track to execute callback at pointOnTrack — Position on Track element that crosses the track

Low-level API (these functions are not available when car is a part of a Train)

Disposal

Function	Description
void dispose()	Completely disposes of the car, i.e. removes it from the yard no matter where it is. The car must be not moving and must not belong to a Train. This function is also called by TrainDispose.

Movement control

Function	Description
void stop()	Stops the car. If it is stopped, does nothing. The car must not be a part of a train.
void go(boolean forward)	Starts the car motion (or changes its direction). The speed must be positive. forward — If true, the car will move forward (front side before rear), otherwise reverse
void couple(boolean infront)	Couples the car with another car that is on a given side. The car must not be a part of a train. infront — If true, couple at front side, otherwise at rear
void decouple(boolean infront)	Decouples the car from another car on a given side. Signals error if the car is not coupled here. The car must not be a part of a train. infront — If true, decouple at front side, otherwise at rear
void setSpeed(double s)	Sets the new speed of the car in meters per second. It applies immediately even if the car is moving. If the speed is set to 0, the car stops if it was moving. The car must not be a part of a train. s — The new speed in meters per second
void setSpeed(double s, SpeedUnits units)	Sets the new speed of the car in given speed units. It applies immediately even if the car is moving. If the speed is set to 0, the car stops if it was moving. The car must not be a part of a train. s — The new speed in given units units — One of speed unit constants

How can we improve this article?