Christopher824: corrected minor formatting of text

2021-01-08T11:07:44Z

corrected minor formatting of text

← Older revision		Revision as of 11:07, 8 January 2021
Line 20:		Line 20:

	- Regularly checking IsGranted() which will return true after the Permit is Granted.		- Regularly checking IsGranted() which will return true after the Permit is Granted.
	~~<bi~~ DO NOT> use IsGranted() continuously to wait because it just wastes CPU time, but there		'''DO NOT''' use IsGranted() continuously to wait because it just wastes CPU time, but there
	may be other uses for this method, such as if we want to request a permit now for use in the		may be other uses for this method, such as if we want to request a permit now for use in the
	future, and don't want to have to listen to the (<m"Permit">, <m "Granted">) message all the		future, and don't want to have to listen to the (<m"Permit">, <m "Granted">) message all the

Christopher824: First entry to page

2021-01-07T11:58:04Z

First entry to page

New page

Permit provides a way of requesting control of a game object resource such as a Track or Junction.

Permits are acquired by requesting them from various game objects. Some objects may only give
out one permit at a time, others may give multiple permits with certain conditions. For example,
a track could permit several trains travelling in the same direction.

Permits are used to stop scripts from 'fighting' over resources in situations such as:
- Two trains want to go opposite directions down a single line; or
- Two trains want to go through the same junction.

When a request is made, a permit is always returned, however it is not automatically granted.
Instead, you have to wait for the permit to reach a 'granted' state. You can determine when a
permit has been granted by:

- Performing a <l gscLangKeyWait wait()> on a message of type (<m"Permit">, <m "Granted">).
Just make sure you check that it is <bi YOUR> permit that was granted. You can do this by
just calling WasGranted() on your permit after receiving the message. The message is sent
to the GameObject passed in to the <b RequestPermit> methods such as
Junction::RequestPermit() or Track::RequestPermitForTrain().

- Regularly checking IsGranted() which will return true after the Permit is Granted.
<bi DO NOT> use IsGranted() continuously to wait because it just wastes CPU time, but there
may be other uses for this method, such as if we want to request a permit now for use in the
future, and don't want to have to listen to the (<m"Permit">, <m "Granted">) message all the
time.

Permits are released automatically. When no more references to a particular Permit remain,
it is automatically released. So you generally don't need to call Release().

Permits can be in one of three states:
- \ref permitStates "REQUESTING"
- \ref permitStates "GRANTED"
- \ref permitStates "RELEASED"

A permit is initially in the \ref permitStates "REQUESTING" state. When the permit is granted,
it moves to the \ref permitStates "GRANTED" state. When Release() is called, or the permit is
revoked, the permit moves to the \ref permitStates "RELEASED" state (A permit can be forced
directly to a \ref permitStates "RELEASED" state from \ref permitStates "REQUESTING".) A permit
can never be re-requested, you must obtain a new permit. Permits are only revoked in exceptional
circumstances, but you don't normally need to deal with this.

See Also:
GameObject, Junction::RequestTrackPermit(), Track::RequestPermitForTrain(),
Trackside::RequestTrackPermit(), Train

Permit - Revision history

Christopher824: corrected minor formatting of text

Christopher824: First entry to page