# Disim Highway Simulator/The LUA API
## Getting Started

Disim allows one to control the individual car behavior and the infrastructure using scripts made in LUA. These scripts have to provide specific functions to Disim (as seen here and here), but Disim also provides functions to them in the form of an object-oriented API.

## LuaCar

This object describes a car running inside the simulator. It has 9 associated functions.
This function returns a number. This number is the position of the vehicle in its current lane. This position is given in meters if the current segment is a straight segment or in radians if it is circular.
This function returns a pointer to a LuaLane object representing the current lane of the vehicle.
This function returns a number giving the current speed of the vehicle in meters per second (m/s).
This function sets the current speed of the vehicle in meters per second (m/s) and sets its acceleration to zero.
This function sets the current acceleration of the vehicle in meters per second squared (m/s^2).
This function sets the next lane to change to. If offset is negative the car will change to the left lane, if it is positive it will change to the right lane, otherwise it will stay on the current lane. A lane change may fail if there is no space on the destination lane.
This function return either the value CAR or TRUCK depending on whether the vehicle is a car or a truck.
This function returns 4 numbers. The first number is the distance from the center of the rear axle to the front bumper, the second is the distance to the rear bumper, the third is the distance to the left-most side and the fourth is the height of the vehicle.
This function returns true if the vehicle is being followed by the camera in the graphical interface (useful to debug). It returns false otherwise.
This function returns true if it is legal to change lanes to the left (this function checks the lane markings on the left side of the current position).
This function returns true if it is legal to change lanes to the right (this function checks the lane markings on the right side of the current position).
This function returns the preferred destination lane as LuaLane object. It returns nil if no destination lane is preferred.
This function returns a pointer to the next LuaRoadActuator with the type equal to TRAFFICLIGHT.

## LuaInfrastructure

This object describes the infrastructure and gives access to all sensors and actuators of the network. It provides 7 functions.
This function returns the name of the current map.
This function returns one pointer to a LuaLane with the name name. If multiple lanes are declared with the same name, just one lane is returned (which one is returned is not specified).
This function returns an array of pointers to all LuaLanes with the name name.
This function returns an array of pointers to all LuaLanes with that are entries of the network.
This function returns one pointer to a LuaRoadSensor with the name name. If multiple sensors are declared with the same name, just one sensor is returned (which one is returned is not specified).
This function returns one pointer to a LuaRoadActuator with the name name. If multiple actuators are declared with the same name, just one actuator is returned (which one is returned is not specified).
This function returns a string in the HH:MM 24-hours format. It takes as input the total time elapsed since the beginning of the simulation.

## LuaLane

This object describes a lane of the highway. Each segment of the highway contains a given number of lane. Each lane provides 17 functions.
This function returns a pointer to the LuaLane object representing the lane directly following the current lane. If there is no such lane, the value nil is returned.
This function returns a pointer to the LuaLane object representing the lane directly preceding the current lane. If there is no such lane, the value nil is returned.
This function returns a pointer to the LuaLane object representing the lane directly on the left the current lane. If there is no such lane, the value nil is returned.
This function returns a pointer to the LuaLane object representing the lane directly on the right the current lane. If there is no such lane, the value nil is returned.
This function returns 1 if the cars on this lane need to merge on the right lane by the end of that lane. This means that there are no next lane and that the cars either need to stop or merge. This function return -1 when merging on the left is needed and 0 otherwise.
This function returns either ENTRY, EXIT or NONE depending on whether the current lane is an entry, an exit or neither respectively.
This function returns either STRAIGHT or CIRCULAR if the current lane is part of a straight segment or a circular segment.
If this lane is straight (getGeometry == STRAIGHT), this function returns the length in meters of that lane. If this lane is not straight, the return value is not defined.
If this lane is circular (getGeometry == CIRCULAR), this function returns the radius of curvature of that lane in meters. If this lane is not circular, the return value is not defined.
If this lane is circular (getGeometry == CIRCULAR), this function returns the angle spanned by that lane in radians. If this returned value is negative the lane is turning to the left and if it is positive, it is turning to the right. If this lane is not circular, the return value is not defined.
This function returns the maximal speed limit allowed on this lane in meters per second (m/s).
This function returns the name of that lane. If no names was specified for that lane, it returns an empty string.
This function returns the index of that lane on its segment. 0 is the index of the left-most lane, 1 is the index of the lane to the right of the left-most lane, and so on.
This function returns the entry rate specified for that lane in vehicles per hour (veh/h).
This function sets the entry rate of that lane in vehicles per hour (veh/h).
This function returns the entry speed specified for that lane in kilometers per hour (km/h).
This function sets the entry speed of that lane in kilometers per hour (km/h). If we do not care about the entry speed of the vehicles we can set this to a negative value.
This function returns the number of vehicle present on that lane.

## LuaRoadSensor

This object represents a sensor in the network. It provides 5 functions.
This function returns the current value computed by this sensor. If this sensor is set to measure flow, it returns a value in vehicles per hour (veh/h); if it is set the measure speed, it returns a value in kilometers per hour (km/h); if it is set to measure density, it returns a value in vehicles per kilometer (veh/km).
This function returns true if there is a car present on the sensor at that moment. It returns false otherwise.
If this sensor is a density sensor (getType == DENSITY), this function returns the number of vehicles present in the detectable area. Otherwise this function returns nothing.
This function returns either FLOW, SPEED or DENSITY depending on the kind of measure it computes.
This function returns the name of that sensor. If no name was specified the empty string is returned.
This function returns a pointer to the Lane to which this sensor belongs.

## LuaRoadActuator

This object represents an actuator in the network. It provides 8 functions.
If the current actuator is a traffic light (getType == TRAFFICLIGHT), this function returns returns either GREEN or RED depending on the current light color of this actuator. A red color means that the cars should not pass. If this actuator is not a traffic light, this function does nothing.
If the current actuator is a traffic light (getType == TRAFFICLIGHT), this function sets the color of the traffic light to be red. If this actuator is not a traffic light, this function does nothing.
If the current actuator is a traffic light (getType == TRAFFICLIGHT), this function sets the color of the traffic light to be green. If this actuator is not a traffic light, this function does nothing.
If the current actuator is a variable speed limit (getType == SPEEDLIMIT), this function sets the speed limit in kilometers per hour (km/h). If this actuator is not a speed limit, this function does nothing.
This function returns either TRAFFICLIGHT or SPEEDLIMIT depending on whether the current actuator is a traffic light or a variable speed sign.
This function returns the name of this actuator. If no name was specified this function returns the empty string.
This function returns a pointer to the LuaLane on which this actuator is present.
This function returns the position of this actuator on its lane in meters if the lane is straight on in radians if the lane is circular.
If the current actuator is a a traffic light (getType == TRAFFICLIGHT), this function returns the average queue length up to the traffic light in seconds (one minute aggregates). If this actuator is not a traffic light, this function does nothing.
If the current actuator is a a traffic light (getType == TRAFFICLIGHT), this function returns the latest queue length up to the traffic light in seconds (the queue duration experienced by the latest car that passed by). If this actuator is not a traffic light, this function does nothing.
If the current actuator is a a traffic light (getType == TRAFFICLIGHT), this function returns the latest vehicle count (number of vehicles that passed through the light). If this actuator is not a traffic light, this function does nothing.

## Additional values and global variables

These variables represent indices in the neighbors array given as an argument to the think function provided by the LUA script controlling the behaviors of the cars (neighbors[LEAD].car refers to the car leading the car being controlled, neighbors[RIGHT_TRAIL].distance is the longitudinal distance from the center of the rear axle of the controlled car to the center of the rear axle of the vehicle on the right lane directly behind the current car).
These variables represent the type of a vehicle as returned by the LuaCar:getType function.
These variables represent the type of a lane as returned by the LuaLane:getType function.
These variables represent the geometry of a lane as returned by the LuaLane:getGeometry function.
These variables represent the type of an actuator as returned by the LuaRoadActuator:getType function.
These variables represent the type of a sensor as returned by the LuaRoadSensor:getType function.
These variables represent the current light color of a traffic light actuator as returned by the LuaRoadActuator:getColor function.