Permit

From TrainzOnline
(Difference between revisions)
Jump to: navigation, search
(First entry to page)
 
m (corrected minor formatting of text)
 
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

Latest revision as of 21:07, 8 January 2021

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.
   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
Personal tools