Lock(name:Str, [hint:Str]):Any

Acquire a lock.

When auto-tasks control parts of the game, it must be made sure that two tasks do not accidentally stomp on each other's feet, or that you don't accidentally change something the auto-task controls. To do that, auto-tasks can acquire locks, which are honored by the user interface. If the user tries to do something which an auto-task claims for itself, a warning message is displayed, citing the auto-task name and the hint given by the Lock invocation.

Locks are acquired using the Lock function in combination with the With statement:

 With Lock(name) Do
   % protected code here
 EndWith

The With Lock statement acquires the lock. The lock is held by the current process until the With statement terminates, usually at the EndWith.

A lock is uniquely identified by a name. No two processes can have a lock at the same time. If a process tries to acquire a blocked lock, this fails with an error.

The following lock names are known by PCC, and honored by the user interface:

pNNN.taxTaxation. Controls the tax change commands (natives/colonists).
pNNN.structStructures (mines/factories/defense). Controls the structure building commands.
sNNN.waypointWaypoint. Controls the ship's waypoint. Setting an Intercept order is considered a waypoint change. Note that locking the waypoint on a fleet member can not always be enforced.

The names are case-insensitive. "NNN" stands for the unit Id (e.g. "p15.tax").

Note: A lock does not block particular operations. Even if someone has the tax lock, the SetColonistTax command will still work. The lock is intended as a hint for user-interface commands to display a warning, but not to block anything.

Note 2: Although Lock formally is a function, using it in other ways than a With Lock statement is not supported; it may work or not, it's not guaranteed. The return value cannot meaningfully be used.

Since: PCC 1.1.2, PCC2 1.99.17

See also: GetLockInfo

This is a testing version.
It may be incomplete, and have more bugs (or features) than the public live version at planetscentral.com.