Class Industry

Revision as of 23:58, 3 February 2010

API Hierarchy
- GSObject *
  - GameObject
    - TrainzGameObject
    - PropertyObject *
      - MeshObject
        MapObject
        SceneryWithTrack
        Buildable
        Industry

Parent class for industry objects.
Industries support attached tracks and triggers and processes.
The methods include support for the transfer of products to ad from vehicles.

Constants & Messages

Load and Unload Driver Command Strings

These values indicate the type of command calling HandleTrain().

public define string LOAD_COMMAND = "load"	Driver command Load
public define string UNLOAD_COMMAND = "unload"	Driver command Unload

Related Messages

Messages sent to and from Industry objects are listed below:

Major	Minor	Source	Destination
Process-Start	process name	Industry	Industry
Process-Stop	process name	Industry	Industry
HandleTrain	Release	Industry	Train
Vehicle	LoadComplete	Industry	Vehicle

See also Object Messages for details of messages exchanged between Vehicles and attached triggers.

Methods

AppendDriverDestinations

public void AppendDriverDestinations(string[ ] destNames, string[ ] destTracks)

Parameters

destNames = An array of names of destinations to be displayed in a menu.
destTracks = An array of attached-track names as defined in the Industry's config.txt
The array size of these two parameters must contain the same number of entries.

Returned Value

None

Syntax

AppendDriverDestinations(Str.Tokens("Bay 1,Bay 2",","),Str.Tokens("track01,track02",","));

Notes

Provides destinations for use of this industry on the Drive To sub-menu.
If the programmer wants the appropriate destinations to appear in the Drive To command's menus, this method must be implemented.
A user readable name and the name of the actual destination track must be provided.
Two arrays are passed in as return arguments, one for the readable names and the other for the track names.
The indexes of each these arrays must correspond.
You don't have to worry about allocating memory for the arrays as Trainzscript expands the array size automatically if this is necessary.

AppendProductList

public void AppendProductList(Asset[ ] productList)

Parameters

productList = Asset array to which products will be added.

Returned Value

None

Syntax

AppendProductList(assets);

Notes

Adds all of the products that the industry is currently capable of producing to the given asset array.
Check that the given products are not already present before calling this method.

BeginLoad

public float BeginLoad(LoadingReport report)

Parameters

report = Report on the current state of the loading operation.

Returned Value

The time required, in seconds, for any animations or other effects required before the loading operation commences.

Notes

Callback method called by Vehicle.LoadProduct() before carrying out any loading operation.

BeginUnload

public float BeginUnload(LoadingReport report)

Parameters

report = Report on the current state of the loading operation.

Returned Value

The time required, in seconds, for any animations or other effects required before the unloading operation commences.

Notes

Callback method called by Vehicle.UnloadProduct() before carrying out any unloading operation.

ClearProcess

public native void ClearProcess(string processName)

Parameters

processName = Name of the process to reset.

Returned Value

None

Syntax

ClearProcess("timberProduction");

Notes

Clears all current inputs and outputs for the named process.

CreateLoadingReport

public LoadingReport CreateLoadingReport(ProductQueue queue, int amount)

Parameters

queue = Industry source queue.
amount = Quantity of product to load.

Returned Value

A newly created LoadingReport object describing the loading operation.

Syntax

LoadingReport report = CreateLoadingReport("brickstore",5000);

Notes

This method creates 'documentation' but doesn't actually perform the operation.

CreateUnloadingReport

public LoadingReport CreateUnloadingReport(ProductQueue queue, int amount)

Parameters

queue = Industry source queue.
amount = Quantity of product to unload.

Returned Value

A newly created LoadingReport object describing the unloading operation.

Syntax

LoadingReport report = CreateUnloadingReport("deliveries",5000);

Notes

This method creates 'documentation' but doesn't actually perform the operation.

EndLoad

public float EndLoad(LoadingReport report)

Parameters

report = Report on the current state of the loading operation.

Returned Value

The time required, in seconds, for any animations or other effects required after the loading operation is completed.

Notes

Callback method called by Vehicle.LoadProduct() after carrying out any loading operation.

EndUnload

public float EndUnload(LoadingReport report)

Parameters

report = Report on the current state of the unloading operation.

Returned Value

The time required, in seconds, for any animations or other effects required after the unloading operation is completed.

Notes

Callback method called by Vehicle.UnloadProduct() after carrying out any unloading operation.

GetLoadTime

public float GetLoadTime(LoadingReport report)

Parameters

report = Report on the current state of the loading operation.

Returned Value

The time required, in seconds, for the loading operation to take place.

Notes

Callback method called by Vehicle.LoadProduct() to detemine the time needed for the loading operation.

GetProcessDuration

public native float GetProcessDuration(string processName)

Parameters

processName = The name of the process to query.

Returned Value

The duration of the named process in seconds.

Syntax

float processTime = GetProcessDuration("outputProcess");

Notes

GetProcessEnabled

public native bool GetProcessEnabled(string processName)

Parameters

processName = The name of the process to query.

Returned Value

True if the specified process is enabled, false otherwise.

Syntax

bool canProcess = GetProcessEnabled("outputProcess");

Notes

GetProcessInput

public native int GetProcessInput(string processName, ProductQueue queue, Asset product)

Parameters

processName = The name of the process to query.
queue = Name of the input queue.
product = Type of product being processed.

Returned Value

The unit quantity of products consumed by this process from the specified queue during one process cycle.

Syntax

int input = GetProcessInput("processName",queue,product);

Notes

GetProcessIOAmount

public native int GetProcessIOAmount(string processName, bool wantInput, int ioIndex)

Parameters

processName = Name of the process to query.
wantInput = True for an input queue, false for an output queue.
ioIndex = Index of the input or output queue to query, use 0 for the first queue defined.

Returned Value

The quantity of product produced or consumed by the specified process during one product cycle, 0 if the information cannot be established.

Syntax

int consumption = GetProcessIOAmount("input",true,0);

Notes

GetProcessIOProduct

public native Asset GetProcessIOProduct(string processName, bool wantInput, int ioIndex)

Parameters

processName = Name of the process to query.
wantInput = True for an input queue, false for an output queue.
ioIndex = Index of the input or output queue to query, use 0 for the first queue defined.

Returned Value

The product for the specified process if possible, null otherwise.

Syntax

Asset product = GetProcessIOProduct("input",true,0);

Notes

GetProcessIOQueue

public native ProductQueue GetProcessIOQueue(string processName, bool wantInput, int ioIndex)

Parameters

processName = Name of the process to query.
wantInput = True for an input queue, false for an output queue.
ioIndex = Index of the input or output queue to query, use 0 for the first queue defined.

Returned Value

The queue related to the specified process if possible, null otherwise.

Syntax

ProductQueue queue = GetProcessIOProduct("input",true,0);

Notes

GetProcessNameList

public native string[ ] GetProcessNameList(void)

Parameters

None

Returned Value

The names of all the processes associated with this Industry object.

Syntax

string[] processes = GetProcessNameList();

Notes

GetProcessOutput

public native int GetProcessOutput(string processName, ProductQueue queue, Asset product)

Parameters

processName = The name of the process to query.
queue = Name of the output queue.
product = Type of product being processed.

Returned Value

The unit quantity of products produced by this process from the specified queue during one process cycle.

Syntax

int output = GetProcessOutput("processName",queue,product);

Notes

GetProcessStarted

public native bool GetProcessStarted(string processName)

Parameters

processName = The name of the process to query.

Returned Value

True if the named process has started, false otherwise.

Syntax

bool hasStarted = GetProcessStarted("production");

Notes

GetRequirements

public Requirement[ ] GetRequirements(void)

Parameters

None

Returned Value

An array of Requirements to enable a waybill listing to be produced.

Notes

A callback method which returns an empty array by default.
This method is called by Trainz to determine the product requirements of an industry so that a waybill listing can be generated for display.
The default implementation in Industry returns an empty array, so the programmer must implement their own overridden version if they want their industry to provide requirements data for waybills.

GetUnloadTime

public float GetUnloadTime(LoadingReport report)

Parameters

report = Report on the current state of the unloading operation.

Returned Value

The time required, in seconds, for the unloading operation to take place.

Notes

Callback method called by Vehicle.UnloadProduct() to detemine the time needed for the unloading operation.

HandleTrain

public bool HandleTrain(Train train, string loadCommand)

Parameters

None
train = Train to be controlled through the industry.
loadCommand = Either of the Load and Unload Driver Command String constants indicating a load or unload command.

Returned Value

True if successful or if the operation is handled by another thread, false on failure. The default implementation always returns false.

Notes

Called by the Load and Unload driver commands to initiate loading or unloading.
The method is called from within a schedule and is permitted to control the train, but not to perform loading or unloading.

HasTrack

public bool HasTrack(string trackName)

Parameters

trackName = Name of attached track section.

Returned Value

True if trackName exists in this Industry, false otherwise.

Syntax

bool IsCoalmine = industry.HasTrack("pithead");

Notes

NotifyProcessFinished

public void NotifyProcessFinished(string processName)

Parameters

processName = Name of the process.

Returned Value

None

Notes

Called by Trainz once when a process is ready to stop running.
You may override this function to provide custom behavior, however, you MUST call the PerformProcessOutput() and PerformProcessFinished() methods.
The call to these methods may be delayed for animation purposes, but it must happen.
As this is not a threaded function, you must not use Sleep() or wait().

NotifyProcessStarted

NotifyProcessStarted(string processName)

Parameters

processName = Name of the process.

Returned Value

None

Notes

Called by Trainz once when a process is ready to start.
You may override this function to provide custom behavior, however, you MUST call the PerformProcessInput() and PerformProcessStarted() methods.
The call to these methods may be delayed for animation purposes, but it must happen.
As this is not a threaded function, you must not use Sleep() or wait().

PerformProcessCancelled

public native void PerformProcessCancelled(string processName)

Parameters

processName = Name of the process to cancel.

Returned Value

None

Syntax

PerformProcessCancelled("production");

Notes

Instructs Trainz to cancel the named process.

PerformProcessFinished

PerformProcessFinished(string processName)

Parameters

processName = Name of the process.

Returned Value

None

Syntax

PerformProcessFinished("production");

Notes

Instructs Trainz to complete the named process.

PerformProcessInput

public native bool PerformProcessInput(string processName)

Parameters

processName = Name of the process.

Returned Value

True if successful, false otherwise.

Syntax

PerformProcessInput("input");

Notes

Instructs Trainz to perform inputs for the named process.
This method should be called once only after each call to NotifyProcessStarted(), unless PerformProcessCancelled() is called first.

PerformProcessOutput

public native bool PerformProcessOutput(string processName)

Parameters

processName = Name of the process.

Returned Value

True if successful, false otherwise.

Syntax

PerformProcessOutput("output");

Notes

Instructs Trainz to perform outputs for the named process.
This method should be called once only after each call to NotifyProcessStarted(), unless PerformProcessCancelled() is called first.

PerformProcessStarted

PerformProcessStarted(string processName)

Parameters

processName = Name of the process.

Returned Value

None

Syntax

PerformProcessStarted("production");

Notes

Instructs Trainz to start the named process.

SetProcessDuration

public native void SetProcessDuration(string processName, float duration)

Parameters

processName = Name of the process.
duration = New duration for the named process, in seconds.

Returned Value

None

Syntax

SetProcessDuration("input",25.0);

Notes

SetProcessEnabled

public native void SetProcessEnabled(string processName, bool enabled)

Parameters

processName = Name of the process.
enabled = True to enable the process, false to disable.

Returned Value

None

Syntax

SetProcessEnabled("input",true);

Notes

SetProcessInput

public native void SetProcessInput(string processName, ProductQueue queue, Asset product, int amount)

Parameters

processName = Name of the process.
queue = Input queue to adjust.
product = Product type to accept as new input into queue.
amount = Quantity of product per process cycle, 0 will remove input requirements.

Returned Value

None

Syntax

SetProcessInput("input",inputQueue,product,50);

Notes

Modifies the input requirements for the specified process.
Using this method will override any existing requirements for the process, whether they have been set previously via this method or predefined in the industry's configuration.

SetProcessOutput

public native void SetProcessOutput(string processName, ProductQueue queue, Asset product, int amount)

Parameters

processName = Name of the process.
queue = Output queue to adjust.
product = Product type to accept as new input into queue.
amount = Quantity of product per process cycle, 0 will remove output requirements.

Returned Value

None

Syntax

SetProcessOutput("input",outputQueue,product,50);

Notes

Modifies the output requirements for the specified process.
Using this method will override any existing requirements for the process, whether they have been set previously via this method or predefined in the industry's configuration.