Classes
class	Infos
	The class to create object that could be use by cEngineLib.GetBestEngine() ie: local myobject = cEngineLib.Infos(); myobject.engine_id = 34; local result = cEngineLib.GetBestEngine(myobject);. More...

Public Member Functions
function	GetAuthor ()
function	GetName ()
function	GetShortName ()
function	GetDescription ()
function	GetVersion ()
function	GetAPIVersion ()
function	GetDate ()
function	CreateInstance ()
function	GetURL ()
function	GetCategory ()
function	LearnEngineFromDepot (depotID, engineID)
	That function will let the library learn engines by creating vehicles and testing them (and sell them), so this function use @VehicleWagonCompatibilityTest Because this function use money , you may prefer handle the learning yourself using ...
function	LearnEngineFromVehicle (vehicleID, all_type)
	That function will let the library learn engines from existing vehicles This function use an existing vehicle to discover properties of engines in it.
function	VehicleUpdateEngineProperties (veh_id)
	That's the library key function, this update properties of engine by looking at the vehicle.
function	GetBestEngine (object, filter)
	This function returns the best engine to use (or couple engine loco+wagon) using the filter you wish.
function	EngineFilter (engine_list, cargo_id, road_type, engine_id, bypass)
	Change an ailist to filter out engine (so watchout what ailist you gives, its content will be change) Default filters are : remove blacklist engine, remove unbuildable, remove incompatible engine, other filters are optionals.
function	VehicleCreate (depot, engine_id, cargo_id=-1)
	Create the vehicle at depot, upto you to add orders...
function	GetLength (engine_id, cargo_id=-1)
	Get the length of an engine when refit to handle cargo_id type.
function	GetCapacity (engine_id, cargo_id=-1)
	Get the capacity of an engine for that cargo type.
function	VehicleGetWeight (vehicle_id, empty=true)
	Get the total weight of a vehicle : only for rail vehicle.
function	VehicleGetMaxTractiveEffort (vehicle_id)
	Get the total max tractive effort a vehicle handle (summing all engines values), only for rail and road vehicle.
function	VehicleGetMaxPower (vehicle_id, KW=false)
	Get the total power of a vehicle (summing all engines values), only for rail and road vehicle.
function	VehicleGetRailTypeUse (vehicle_id)
	Get the railtype the vehicle is running on (if you run a vehicle on different railtype, the answer will depend on which ones it was running when checked)
function	VehicleGetMaxSpeed (vehicle_id)
	Return the maximum speed the vehicle can do with its engine, railtype and wagons in use.
function	IsLocomotive (engine_id)
	Check if an engine is a locomotive.
function	VehicleIsMultiEngine (vehicle_id)
	Check if a train use multi locomotive or is multihead if the API support the function.
function	VehicleGetNumberOfLocomotive (vehicle_id)
	Get the number of locomotive a vehicle have: note that two heads engine will be count as two locomotives!
function	VehicleLackPower (vehicle_id, aim_speed=0)
	Look at the given vehicle, get its first loco engine and return true if you lack enough power (for original acceleration model) or tractive effort (for realistic model) to run that vehicle at low speed on hills (at ~15% of its maxspeed) It handle the game setting "train_slope_steepness" (http://wiki.openttd.org/Train_slope_steepness) It handle the "train_accelaration_model", increase x2 the aim speed when original model is use.
function	VehicleGetNumberOfWagons (vehicle_id)
	Get the number of wagons a vehicle have (excluding loco engine)
function	VehicleGetRandomWagon (vehicle_id)
	Get the position of a random wagon in the train.
function	IncompatibleEngine (engine_one, engine_two)
	Mark engine_one and engine_two not compatible with each other This could only be use with trains.
function	CompatibleEngine (engine_one, engine_two)
	Mark engine_one and engine_two compatible with each other This could only be use with trains.
function	AreEngineCompatible (engine, compare_engine)
	Check if engine1 is usable with engine2.
function	VehicleWagonCompatibilityTest (vehicleID, wagonID)
	Test compatibilty of a wagon engine with the vehicle.
function	CanPullCargo (engine_id, cargo_id, bypass=false)
	Check if the engine can pull a wagon with the given cargo.
function	IsEngineBlacklist (engine_id)
	Return if that engine is blacklist or not.
function	BlacklistEngine (engine_id)
	Add an engine to the blacklist.
function	IsDepotTile (tile)
	Check if the tile is a depot.
function	GetDepotType (tile)
	Get the type of depot found at tile.
function	VehicleIsGoingToStopInDepot (vehicle_id)
	Answer if the current order (even not in its list) is going to depot and if it will stop there.
function	VehicleOrderSkipCurrent (vehicle_id)
	Skip the current order in vehicle, it doesn't check any conditionnal orders and just jump to next order in position.
function	VehicleOrderClear (vehicle_id)
	Unshare and clear the order list of a vehicle.
function	RailTypeGetFastestType (engineID=-1)
	This will browse railtype and return the railtype that can reach the fastest speed or the fastest railtype a given engine could use.
function	RailTypeGetFastestTypeForCargo (cargoID, bypass=false)
	This will browse railtype and return the railtype that can reach the fastest speed to pull a cargo Even if you can easy get the fastest railtype, it is harder to actually find one that is usable with a cargo.
function	RailTypeGetSpeed (RT=-1)
	Return the speed of the given railtype, so to get the speed of the current fastest railtype, cEngineLib.RailTypeGetSpeed(cEngineLib.RailTypeGetFastestType());.
function	VehicleRestrictLength (vehicle_id, max_length)
	This restrict a train length to met max_length, selling wagons only to met it (so a train, stopped, in a depot), the vehicle size may still not met the length if it is bigger because of its loco(s) length in it.
function	GetMaxWagons (engines, max_length, cargo_id=-1)
	Get the number of wagons we could add to stay below max_length.
function	SetAPIErrorHandling (output)
	Enable or disable errors message.
function	GetAPIError ()
	Get the last error string the API report.
function	SetMoneyCallBack (money_func)
	Set the API to use your money callback function, a function run by the API when it need to get money The callback function will be called with "amount" as parameter, ie: cEngineLib.SetMoneyCallBack(myAI.MoneyGiver); with <function myAI::MoneyGiver(amount) { // grant the money }.
function	EngineCacheInit ()
	This will browse engines so they are all added to the engine database, faster next access to any engine properties.
function	DirtyEngineCache (eng_type)
	This will dirty the cache of eng_type, forcing next access to the cache to sent fresh infos.
function	GetEngineList (eng_type)
	Return a cache AIList of engines of the type "eng_type".
function	DumpLibStats ()
	The lib will output to the console some stats about itself, that's of course a debug feature, but it might help you.
function	Engine_Stats (engine_id)
function	ErrorReport (error)
function	ErrorReport_NORAILTRACK ()
function	ErrorReport_INVALIDVEHICLE (id)
function	ErrorReport_INVALIDCARGO (id)
function	SetUsuability (engine_one, engine_two, flags)
function	IsCoupleTested (engine_one, engine_two)
function	SetRailTypeSpeed (engineID)
function	Load (e_id)
function	Save ()
function	EngineIsKnown (engine_id)
function	GetKnownLevel (engine_id)
function	Filter_EngineTrain (engine_list, object)
function	Filter_EngineGeneric (engine_list, object)
function	GetCallbackResult (callback, callback_param)
function	EngineToName (engID)
function	CheckEngineObject (eo)
function	GetMoney (amount)

Public Attributes
	engine_id = null
	id of the engine
	cargo_capacity = null
	capacity per cargo item=cargoID, value=capacity when refit
	cargo_length = null
	that's the length of a vehicle depending on its current cargo setting
	cargo_pull = null
	only for locos, cargobits it is able to pull.
	is_known = null
	0: never seen that engine, 1: basic tests made 2: loco tests made
	usuability = null
	compatibility list of wagons & locos, item=the other engineID value=cargobits 1 compatible, 0 incompatible with that cargo

Static Public Attributes
static	VT_RAIL = AIVehicle.VT_RAIL
static	VT_ROAD = AIVehicle.VT_ROAD
static	VT_WATER = AIVehicle.VT_WATER
static	VT_AIR = AIVehicle.VT_AIR
static	VT_RAIL_LOCO = AIVehicle.VT_AIR + 1
static	VT_RAIL_WAGON = AIVehicle.VT_AIR + 2
static	_cel_ebase = {}
static	_cel_blacklist = AIList()
	our base where engines are store
static	_cel_RT = AIList()
	the blacklist engine
static	_cel_config = "", null]
	hold configuration options and error message, you have functions to alter that.
static	_cel_cache = [null, null, null, null, null, null]
	we cache enginelist result here

Detailed Description

cEngineLib is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or any later version.

cEngineLib is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this AI Library. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. A library with helpers for engine and vehicle handling.

Member Function Documentation

function cEngineLib::AreEngineCompatible	(	engine	,
		compare_engine
	)

Check if engine1 is usable with engine2.

For trains/wagons only. It is inside the default filter for trains, but your custom filter better use it too.

Parameters

engine	engine id of the first engine
compare_engine	engine id of the second engine

Returns: true if you can use them, if we never check their compatibilities, it will return true

function cEngineLib::BlacklistEngine ( engine_id )

Add an engine to the blacklist.

Parameters

engine_id The engine to get blacklist

function cEngineLib::CanPullCargo	(	engine_id	,
		cargo_id	,
		bypass	= `false`
	)

Check if the engine can pull a wagon with the given cargo.

Exactly the same as AIEngine.CanPullCargo if the bypass is set to false The ai_special_flag (nfo property 08) for newGRF is set if an engine can pull a cargo or not. But the newGRF can also allow/disallow what couple cargo/engine you are allowed to use. So, if the newGRF didn't disallow cargo/engine couple, but have its ai_special_flag set to disallow that, we could ignore it and pull the cargo we wish (as long as some compatible wagons exist to carry it). That's what the bypass param is for. The trick to get the answer: if the loco can use wagonX and wagonX can be refit to potatoes, then loco is able to pull potatoes... In order to know if wagonX can be use with that loco you need to test that with So until the loco has been test, the result is the one from AIEngine.CanPullCargo.

Parameters

engine_id	The engine to check
cargo_id	The cargo to check
bypass	Set to false to respect newGRF author wishes, set it to true to allow bypassing the ai_special_flag

Returns: true if it can pull the cargo, false if it cannot.

function cEngineLib::CompatibleEngine	(	engine_one	,
		engine_two
	)

Mark engine_one and engine_two compatible with each other This could only be use with trains.

Use in

Parameters

engine_one	engine id of the first engine
engine_two	engine id of the second engine

function cEngineLib::DirtyEngineCache ( eng_type )

This will dirty the cache of eng_type, forcing next access to the cache to sent fresh infos.

The cache itself has a 7 openttd days lifetime ; but in case you wish a fresh list. The lib dirty the cache also when a new engine is found in a vehicle (and not because of the event)

Parameters

eng_type The engine type to dirty, it could be AIVehicle.VT_RAIL, AIVehicle.VT_ROAD, AIVehicle.VT_WATER or AIVehicle.VT_AIR

function cEngineLib::EngineCacheInit ( )

This will browse engines so they are all added to the engine database, faster next access to any engine properties.

If you want use this, it should be called early in your AI, else its usage will get poorer with time. It now also use

function cEngineLib::EngineFilter	(	engine_list	,
		cargo_id	,
		road_type	,
		engine_id	,
		bypass
	)

Change an ailist to filter out engine (so watchout what ailist you gives, its content will be change)

Default filters are : remove blacklist engine, remove unbuildable, remove incompatible engine, other filters are optionals.

Parameters

engine_list	an ailist of engine id
cargo_id	if -1 don't filter, if set, filter engines that cannot be refit to use that cargo (or pull other engines using that cargo)
road_type	: if -1 don't filter, if set, filter engines that are limit (by the roadtype, railtrack type or airport type), see object.engine_roadtype for posssible values.
engine_id	: if -1 don't filter, if it's a wagon filter out locos that cannot pull it, if it's a loco filter out wagons that loco cannot pull
bypass	: alter the cargo & train filter decision : see bypass value for more

function cEngineLib::GetAPIError ( )

Get the last error string the API report.

Returns: A string.

function cEngineLib::GetBestEngine	(	object	,
		filter
	)

This function returns the best engine to use (or couple engine loco+wagon) using the filter you wish.

If you don't provide a filter it will use its own internal one, that is basic, but functional and should gives not bad result. The accuracy of the result depend on the limits you put yourself in the query, but also if the vehicle has been create and test by the lib. If you gives it a real depot, it will run (limit to the engine it think is the best) and loop to find if it's still the best one once it get test, so even it limit to one engine only, it can feed it one by one until it get a stable result. As this function may use your money, make sure the AI have enough money to buy stuff. See

Parameters

object

Here's the different options :

object.depot : if valid, this put a restriction to rail/road type. It will test the result prior to returning it (and use your money so). If depot is invalid or -1 get theorical results only ; accuracy depend on what engines the lib has learned.
object.engine_id : Not use except for VT_RAIL query.
- if it's a wagon engine: restrict to find a locomotive that can pull this wagon.

if it's a locomotive: restrict to find a wagon that could be use with that locomotive.
if set to -1: allow finding best locomotive & wagon couple.

object.engine_type : if depot == -1 this must be set as the AIVehicle.VehicleType of vehicle you want the query to be done.

object.bypass : only use with VT_RAIL. true or false. Set it true to bypass ai_special_flag (see ).
object.cargo_id : This could restrict the search for this cargo, -1 to not use cargo restriction
object.engine_roadtype : This add a special restriction to the search, -1 to add none
- for VT_ROAD: it could of AIRoad.ROADTYPE_ROAD or AIRoad.ROADTYPE_TRAM
- for VT_RAIL: it is a railtrack restriction. It is not use when object.depot is valid, as it will be the one of the depot use.
- for VT_AIR: it could be AIAirport.PT_HELICOPTER, AIAirport.PT_BIG_PLANE or AIAirport.PT_SMALL_PLANE to restrict search on this kind of plane only.

for VT_WATER: it's not use.

Parameters

filter A function that will be called to apply your own filter and heuristic on the engine list. If null a private function will be used. The function must be : function myfilter(AIList, object) For VT_RAIL the filter will be called with two different list, 1 for locomotive, and 2nd for the wagons. So be sure to check if AIEngine.IsWagon(object.engine_id) or any engine in the list you get, to see if your filter is working on a loco or a wagon.

Returns: An array with the best engines : [0]= -1 not found, [0]=engine_id water/air/road, rail : [0]=loco_id [1]=wagon_id [2] railtype

function cEngineLib::GetCapacity	(	engine_id	,
		cargo_id	= `-1`
	)

Get the capacity of an engine for that cargo type.

Accuracy depend on

Parameters

engine_id	The engine to get the capacity of
cargo_id	If -1, it's the current refit cargo, else the cargo id to get the capacity for.

Returns: the capacity, 0 if the cargo is not support or on error

function cEngineLib::GetDepotType ( tile )

Get the type of depot found at tile.

Parameters

tile	a valid tile, should be a tile with a depot

Returns: the type of depot found at tile (AIVehicle.VT_RAIL...) or -1 on error

function cEngineLib::GetEngineList ( eng_type )

Return a cache AIList of engines of the type "eng_type".

Faster access to the very same list and lesser this effect http://bugs.openttd.org/task/6213 as you will work on a shorter list. Note that the lists are stock lists of engines EXCEPT blacklist engines that are remove from it (but it still include non buildable engine).

Parameters

eng_type It could of AIVehicle.VT_RAIL, AIVehicle.VT_ROAD, AIVehicle.VT_WATER or AIVehicle.VT_AIR. But you can also use the special cEngineLib.VT_RAIL_LOCO to get only loco engine, or cEngineLib.VT_RAIL_WAGON to get only wagon engine. This should replace occurances of AIEngineList() in your code. To ease handling AIVehicle.VT_ have their cEngineLib.VT_ equivalent.

Returns: an AIList of engines of the eng_type type, on error you will get an empty AIList.

function cEngineLib::GetLength	(	engine_id	,
		cargo_id	= `-1`
	)

Get the length of an engine when refit to handle cargo_id type.

Accuracy depend on

Parameters

engine_id	the engine id to query
cargo_id	the length of the engine when refit to that cargo, if -1 the length of the engine with its default cargo

Returns: length of engine or 0 on error (note that VT_AIR will always be 0 length)

function cEngineLib::GetMaxWagons	(	engines	,
		max_length	,
		cargo_id	= `-1`
	)

Get the number of wagons we could add to stay below max_length.

This will return inacurate results or error if the wagon or loco was never built.

Parameters

engines	an array with [0] the loco engine, and [1] the wagon engine. Accept also the array return by GetBestEngine function
max_length	The length to match : don't forget to x16 it if you aim a tile length: ie: limit to 3 tiles, max_length = 3*16
cargo_id	the cargo the wagon will use (-1 for default wagon size, because wagon size can change depending on the cargo use).

Returns: -1 on error, else return the maximum number of wagons usable within that length limit

function cEngineLib::IncompatibleEngine	(	engine_one	,
		engine_two
	)

Mark engine_one and engine_two not compatible with each other This could only be use with trains.

Use in

Parameters

engine_one	engine id of the first engine
engine_two	engine id of the second engine

function cEngineLib::IsDepotTile ( tile )

inline

Check if the tile is a depot.

Parameters

tile	a valid tile

Returns: true if tile is a valid depot of any type, false if not or on error.

function cEngineLib::IsEngineBlacklist ( engine_id )

Return if that engine is blacklist or not.

The lib itself doesn't need to blacklist any engines (yet).

Parameters

engine_id The engine to get check

Returns: True if engine is blacklist, false if not

function cEngineLib::IsLocomotive ( engine_id )

Check if an engine is a locomotive.

Parameters

engine_id the engine to check

Returns: True if it's a locomotive, false if not or invalid...

function cEngineLib::LearnEngineFromDepot	(	depotID	,
		engineID
	)

That function will let the library learn engines by creating vehicles and testing them (and sell them), so this function use @VehicleWagonCompatibilityTest

Because this function use money , you may prefer handle the learning yourself using ...

But this function really automates everything for you. The learning is done at the given depot and it will create all engines it could with the money you have (and sell them fast to get your money back), keep in mind, that a rail depot is limited by its railtype, so you can't build (and learn) a maglev engine in a non maglev depot (look at engine == -2 for that). Because this function do all the job, the accuracy of all other functions of the lib will goes upto 100% Unlike VehicleUpdateEngineProperties, this function also check compatibility of locos and wagons, making "bypass" usage 100% accurate.

Parameters

depotID	a valid depot of any type (an airport is a depot)
engineID	if a valid engineID it will test that engine only (but also other known engines for new wagons), giving 100% accuracy result for this engine. if -1 it will test all engines from that depot. This increase accuracy to 100% on all engines of that depot type ; except VT_RAIL that need more.

function cEngineLib::LearnEngineFromVehicle	(	vehicleID	,
		all_type
	)

That function will let the library learn engines from existing vehicles

This function use an existing vehicle to discover properties of engines in it.

It is similar and actually do exactly the same as on all vehicles type except rails as this function will also fill the compatibility of engine while the other cannot. So it use what was previously create to learn from it. If it find a depot it will called with the engineID taken from that vehicle. Because it could be use with more than one vehicle, but also more than one vehicle type, it can learn from all vehicles in one go. Making it a good helper when your AI is loading a game and the lib can learn from what was create previously.

Parameters

vehicleID	if it's a valid vehicleID it will learn only from that vehicle
all_type	if vehicleID is invalid only, all vehicles from the AIVehicle.VehicleType type will be check. With AIVehicle.VT_INVALID all vehicles of any type.

function cEngineLib::RailTypeGetFastestType ( engineID = -1 )

This will browse railtype and return the railtype that can reach the fastest speed or the fastest railtype a given engine could use.

Parameters

engineID the engineID to get its best railtype to use with it, if -1 get the current fastest railtype

Returns: -1 if no railtype is found

function cEngineLib::RailTypeGetFastestTypeForCargo	(	cargoID	,
		bypass	= `false`
	)

This will browse railtype and return the railtype that can reach the fastest speed to pull a cargo Even if you can easy get the fastest railtype, it is harder to actually find one that is usable with a cargo.

If you have no train able to pull it, or no wagon able to be refit to it with that railtype, the fastest railtype is finally not usable to handle this cargo. So the return answer from this function is really the fastest railtrack type with a loco and wagon that exists and that you could use with that cargo, and not simply the fastest railtrack type. It's accuracy depend on ; so range from 0% when bypass is enable and no loco has been test, to 100% if tests were made. And without enabling bypass, its accuracy depend on AIEngine.CanPullCargo that is 0% as it will never answer if the loco have a real wagon that could be refit to pull that cargo.

Parameters

cargoID	the cargoID to get the railtype with a train able to pull that cargo and a compatible wagon with that loco, refitable to handle that cargo.
bypass	enable/disable it, see

Returns: -1 if no railtype is found (it mean no train can pull that cargo or no wagon can be refit for it, or just because no railtype are there)

function cEngineLib::RailTypeGetSpeed ( RT = -1 )

Return the speed of the given railtype, so to get the speed of the current fastest railtype, cEngineLib.RailTypeGetSpeed(cEngineLib.RailTypeGetFastestType());.

Parameters

RT	The RailType to get the speed, if -1 we will return the fastest one.

Returns: -1 if no railtype is found

function cEngineLib::SetAPIErrorHandling ( output )

Enable or disable errors message.

Those are only errors at using the API, not errors report by the NOAI API

Parameters

output True and the API will output its errors messages. False to disable this. You can still get the last error with GetAPIError

function cEngineLib::SetMoneyCallBack ( money_func )

Set the API to use your money callback function, a function run by the API when it need to get money The callback function will be called with "amount" as parameter, ie: cEngineLib.SetMoneyCallBack(myAI.MoneyGiver); with <function myAI::MoneyGiver(amount) { // grant the money }.

Parameters

money_func A valid function from your AI that should raise your account to to the wanted "amount" of money

function cEngineLib::VehicleCreate	(	depot	,
		engine_id	,
		cargo_id	= `-1`
	)

Create the vehicle at depot, upto you to add orders...

It will also refit the vehicle to the given cargo. As this function use your money, make sure the AI have enough money to buy stuff. See This function use limit to the vehicle you are creating, so it allow the lib to learn from each creation you do.

Parameters

depot	a depot to use to create the vehicle
engine_id	the engine to create the vehicle
cargo_id	if set to -1 you get just the vehicle, otherwise the engine will be refit to handle the cargo (if possible)

Returns: vehileID of the new vehicle or -1 on error. No error if you ask to refit a vehicle that cannot be refit to that cargo ; but if the vehicle could be refit and it cannot do it, it will return -1 and sell it.

function cEngineLib::VehicleGetMaxPower	(	vehicle_id	,
		KW	= `false`
	)

Get the total power of a vehicle (summing all engines values), only for rail and road vehicle.

Parameters

vehicle_id	The vehicle id
KW	Per default the function return power in HP (like the AI API), if set to true, you will get the power in KW and the return value will be a float number.

Returns: the total power of the vehicle in HP or KW, -1 on error, 0 if not a road or rail vehicle

function cEngineLib::VehicleGetMaxSpeed ( vehicle_id )

Return the maximum speed the vehicle can do with its engine, railtype and wagons in use.

However it doesn't check if the engine has enough power to actually reach that limit. It takes the setting "wagon_speed_limits" (see http://wiki.openttd.org/Wagon_speed_limits) and the railtype limit.

Parameters

vehicle_id The vehicle id to get its maximum speed. If the vehicle is not of AIVehicle.VT_RAIL it return the result of AIEngine.GetMaxSpeed

Returns: The maximum speed reachable by this vehicle. -1 on error.

function cEngineLib::VehicleGetMaxTractiveEffort ( vehicle_id )

Get the total max tractive effort a vehicle handle (summing all engines values), only for rail and road vehicle.

Parameters

vehicle_id The vehicle id of a rail or road vehicle

Returns: the total tractive effort in KN, -1 on error, 0 if not a road or rail vehicle

function cEngineLib::VehicleGetNumberOfLocomotive ( vehicle_id )

Get the number of locomotive a vehicle have: note that two heads engine will be count as two locomotives!

Parameters

vehicle_id the vehicle to check, must be a rail vehicle

Returns: 0 if no locomotive/not a train, or the number of locomotive in the vehicle

function cEngineLib::VehicleGetNumberOfWagons ( vehicle_id )

Get the number of wagons a vehicle have (excluding loco engine)

Parameters

vehicle_id the vehicle to check, must be a rail vehicle

Returns: 0 if not a train or without wagon, or the number of wagons in the vehicle

function cEngineLib::VehicleGetRailTypeUse ( vehicle_id )

Get the railtype the vehicle is running on (if you run a vehicle on different railtype, the answer will depend on which ones it was running when checked)

Parameters

vehicle_id The vehicle id to get the RailType in use

Returns: the RailType in use, AIRail.RAILTYPE_INVALID on error

function cEngineLib::VehicleGetRandomWagon ( vehicle_id )

Get the position of a random wagon in the train.

Parameters

vehicle_id the vehicle to check, must be a rail vehicle

Returns: -1 if not a train or no wagon. A place (position) with a wagon in that train

function cEngineLib::VehicleGetWeight	(	vehicle_id	,
		empty	= `true`
	)

Get the total weight of a vehicle : only for rail vehicle.

The function takes freight_trains setting and if the cargo is freight to calc the weight. See: http://wiki.openttd.org/Freight_trains

Parameters

vehicle_id	The vehicle id of the vehicle to calc its total weight
vehicle_id	An array with [loco engine, number of locos, wagon engine, number of wagons], so you could get what a non existing vehicle weight will be after creation. Set "number" to 0 to not pass a loco or wagon engine but array must be of size 4.
empty	true to get the total weight when empty, false to get the total weight when full (and this include filling loco with cargo if loco handle some)

Returns: the total of loco + all wagons weight of the vehicle, -1 on error

function cEngineLib::VehicleIsGoingToStopInDepot ( vehicle_id )

Answer if the current order (even not in its list) is going to depot and if it will stop there.

Servicing at depot is not stopping at it.

Parameters

vehicle_id the vehicle to check

Returns: true only if the vehicle is going to stop at a depot, false if it does not or on error.

function cEngineLib::VehicleIsMultiEngine ( vehicle_id )

Check if a train use multi locomotive or is multihead if the API support the function.

Parameters

vehicle_id the vehicle to check

Returns: True if it have more than 1 locomotive or 1 multihead, false for any others reason...

function cEngineLib::VehicleLackPower	(	vehicle_id	,
		aim_speed	= `0`
	)

Look at the given vehicle, get its first loco engine and return true if you lack enough power (for original acceleration model) or tractive effort (for realistic model) to run that vehicle at low speed on hills (at ~15% of its maxspeed) It handle the game setting "train_slope_steepness" (http://wiki.openttd.org/Train_slope_steepness) It handle the "train_accelaration_model", increase x2 the aim speed when original model is use.

(http://wiki.openttd.org/Realistic_acceleration) Even its accuracy isn't that bad, don't take its "true" answer as-is but keep some limit, To simplify the example, if you need 1000hp to pull 5 wagons and use a loco with 100hp, it would then return true until you use 10 locos, not really something usable.

Parameters

vehicle_id	The vehicle id of a rail vehicle
aim_speed	The calc are base on a train ability to aim a certain mimimum speed when climbing with its load, per default (0) the aim_speed will be 15% of maximum speed of the train engine (and a non-alterable minimum of 15spd). You can pass your own custom aim_speed to use.

Returns: true if you should add more engine to that vehicle, -1 on error

function cEngineLib::VehicleOrderClear ( vehicle_id )

Unshare and clear the order list of a vehicle.

Parameters

vehicle_id the vehicle to work on

Returns: true if order list is clear, false on error

function cEngineLib::VehicleOrderSkipCurrent ( vehicle_id )

Skip the current order in vehicle, it doesn't check any conditionnal orders and just jump to next order in position.

If order was last, it jump to order 0

Parameters

vehicle_id the vehicle to skip current order

Returns: the new order position, -1 on error (mostly, a vehicle with empty order, but anything: destination too far...).

function cEngineLib::VehicleRestrictLength	(	vehicle_id	,
		max_length
	)

This restrict a train length to met max_length, selling wagons only to met it (so a train, stopped, in a depot), the vehicle size may still not met the length if it is bigger because of its loco(s) length in it.

Parameters

vehicle_id	A train with wagons you want to limit its length
max_length	The length to match : don't forget to x16 it if you aim a tile length: ie: limit to 3 tiles, max_length = 3*16

Returns: -1 on error, else return the number of wagons removed (that could be 0)

function cEngineLib::VehicleUpdateEngineProperties ( veh_id )

That's the library key function, this update properties of engine by looking at the vehicle.

This get enough information to get 100% accuracy (but only for this engine) on any vehicle type except rail, that need another step see This function should be called after a vehicle creation, so the base is filled with its values,

Parameters

veh_id a valid vehicle_id that we will inspect to get informations about its engine

function cEngineLib::VehicleWagonCompatibilityTest	(	vehicleID	,
		wagonID
	)

Test compatibilty of a wagon engine with the vehicle.

For rails vehicle only. This autofill compatibilty state of both engines.

Parameters

vehicleID	a valid vehicle, stopped in a depot, with a locomotive in it
wagonID	the engine wagon type to test.

Returns: true if you can, but false doesn't mean you cannot! Use AreEngineCompatible to get the answer.

Member Data Documentation

cEngineLib::_cel_config = "", null]

static

hold configuration options and error message, you have functions to alter that.

cEngineLib::_cel_RT = AIList()

static

the blacklist engine

item = the railtype, value = maximum speed doable

cEngineLib::cargo_pull = null

only for locos, cargobits it is able to pull.

The documentation for this class was generated from the following files:

library.nut
main.nut

Classes

Public Member Functions

Public Attributes

Static Public Attributes

Detailed Description

Member Function Documentation

Member Data Documentation