Lock Pools


In many circumstances, the player's controls are intended to become unresponsive. For example, when the player gets stunned, or enters a boss chamber, or talks to an NPC, or uses certain utilities. In previous versions of the engine, the controls status were decided by variables such as canHit, canMove, canStep, etc.

One of several flaws with the previous system was that multiple control locks could not stack. For example, if one object locked up the player's controls, and then a second object locked them, the first object could unlock the controls and then the player would be able to move despite the fact that the second object still intended for the player to have their controls locked.

Lock Pools allow multiple sources of locks to stack together and independently lock/unlock the player's controls. Other systems can also use lock pools. global.frozen may eventually be replace with a lock pool.


Each state that can be locked or unlocked independently (such as the player's ability to move, jump, shoot, etc.) is assigned a Lock Pool. A pool or set of pools can be locked by invoking lockPoolLock(), which returns the value of a lock. To unlock, this same lock value must later be returned (or released) when the the pool is to be unlocked. A lock is said to be checked out when it has not yet been returned. A pool is unlocked when there are no currently checked-out locks. As a convenience feature, multiple lock pools may be locked simultaneously, returning a single shared lock among them.

Lock Pools also make use of assert statements to ensure that they are used properly. If a lock pool is misused -- for example, if a checked-out lock is returnred more than once -- then the game crashes with a helpful error message. This is intentional and is designed to force the programmer to not write code with latent unnoticed bugs.


Script Arguments Return Value Description
lockPoolInit() Sets up the lock pool system. Should be called once at the beginning of the game.
lockPoolNew() returns the lock pool ID. Creates a new lock pool, returning its ID for later use (much like data structures in GML).
lockPoolDestroy(pool) pool: the lock pool to destroy. deletes the given pool. This is used to free up resource. ~~If there are any currently checked-out locks on the pool when it is destroyed, then it will be marked with a tombstone and the resource will only be freed when all locks are returned. Locks expire automatically on tombstoned pools when a room ends, after which returning the lock could cause undefined behaviour.~~*
lockPoolLock(pools...) pools...: the pool or set of pools to lock. the checked-out lock. Locks the given lock pool until all checked-out locks are returned.
lockPoolRelease([pools...], lock) [pools...]: an optional list of pool IDs. lock: a checked-out lock. returns the value 0. Releases the given lock. The game wil crash if the lock value supplied is not a checked-out lock, so never return the same lock twice. As a convenience feature, if the value 0 is passed into the the lock argument, then nothing will occur. Since 0 is also returned by the lock, a typical usage will look like lock = lockPoolRelease(lock). Running this line multiple times in a row will not cause a crash, whereas lockPoolRelease(lock) is liable to. If a list of lock pools is supplied, then the script will assert that the lock is checked out on all the given lock pools and no others, crashing the game if it is not the case. This is helpful to ensure that the lock pool system is never misused.
lockPoolReleaseAll(pools...) pools...: the list of pools to release all locks on. Releases all checked-out locks on the given pool. No currently checked-out locks should be returned after this, or the game will crash. As a result, this function should not be used except in circumstances where it is possible to guarantee that no lock will ever be returned to the given pools again.
lockPoolExists(pool) pool: a lock pool ID. true or false Returns true if the given lock pool exists (has not been destroyed). ~~Tombstoned lock pools still exist.~~*
isLocked(pools...) pools...: a list of lock pools. true or false Returns true if any of the given pools are locked, and false if none of them are.


The following code creates two lock pools, checks out three locks including one on both pools, and then returns all three of them. It then destroys the lock pool, freeing the resource.

// create lock pools
lockPoolA = lockPoolNew();
lockPoolB = lockPoolNew();

print(isLocked(lockPoolA)); // false
print(isLocked(lockPoolB)); // false
print(isLocked(lockPoolA, lockPoolA)); // false

// check out some locks
lockA = lockPoolLock(lockPoolA);

print(isLocked(lockPoolA)); // true
print(isLocked(lockPoolB)); // false
print(isLocked(lockPoolA, lockPoolA)); // true

lockB  = lockPoolLock(lockPoolB);
lockAB = lockPoolLock(lockPoolA, lockPoolB);

print(isLocked(lockPoolA)); // true
print(isLocked(lockPoolB)); // true
print(isLocked(lockPoolA, lockPoolA)); // true

// return one lock
lockA = lockPoolRelease(lockPoolA);

// lockPoolA is still locked due toe lockAB being checked out
print(isLocked(lockPoolA)); // true

// release all locks
lockB = lockPoolRelease(lockPoolB, lockB); // specifying lockPoolB is optional
lockB = lockPoolRelease(lockB); // because lockB has the value 0, this does nothing
lockAB = lockPoolRelease(lockAB);

print(isLocked(lockPoolA)); // false
print(isLocked(lockPoolB)); // false
print(isLocked(lockPoolA, lockPoolA)); // false

// destroy lock pools

Commonly-used lock pools

Here are a list of lock pools and their descriptions. Note that the player control locks have both a global and an instance version. The instance version allows locking the controls for a single instance of objMegaman (e.g. if one objMegaman instance is caught in a honey pool and the other isn't). The global version locks the controls for all objMegaman instances, which is useful for cutscenes.

Name Owner Description
global.timeStopped Is time stopped for enemies?
global.playerFrozen Is time stopped for the players?
localPlayerLock[PL_LOCK_MOVE] objMegaman Can the player walk horizontally or move in the air horizontally? This is not a master lock; one can lock this form of movement but still allow jumping and climbing and sliding.
localPlayerLock[PL_LOCK_PHYSICS] objMegaman (deprecated?)
localPlayerLock[PL_LOCK_TURN] objMegaman Can the player turn around? (Does not affect turning while sliding)
localPlayerLock[PL_LOCK_GRAVITY] objMegaman Does the player experience gravity?
localPlayerLock[PL_LOCK_SHOOT] objMegaman Can the player shoot?
localPlayerLock[PL_LOCK_SLIDE] objMegaman Can the player slide?
localPlayerLock[PL_LOCK_PAUSE] objMegaman Can the player pause? (Also currently used for interaction with NPCs, but this may be refactored.)
localPlayerLock[PL_LOCK_CLIMB] objMegaman Can the player climb ladders?
localPlayerLock[PL_LOCK_JUMP] objMegaman Can the player jump?
localPlayerLock[PL_LOCK_CHARGE] objMegaman Can the player charge their weapon?
localPlayerLock[PL_LOCK_SPRITECHANGE] objMegaman Can the player change sprites?
global.playerLock[...] All the same as above, but global versions.
global.playerLock[PL_LOCK_SPAWN] Can players respawn currently? (Co-op). This is meaningless for individual instances of objMegaman because they are already spawned.
PL_LOCK_MAX This is not a lock pool, but if you want to add more lock pool PL_LOCK constants to the player lock system then make sure that this value is greater than all the other PL_LOCK_ constants.

Convenience scripts

It is a bit of a pain to type out isLocked(localPlayerLock[PL_LOCK_MOVE], localPlayerLock[PL_LOCK_JUMP]) || isLocked(global.playerLock[PL_LOCK_MOVE], global.playerLock[PL_LOCK_JUMP]), so the script playerIsLocked() is provided. This can be used like playerIsLocked(PL_LOCK_MOVE, PL_LOCK_JUMP).