Clarify TriggerSleepAction

[Luashine]

https://lep.duckdns.org/app/jassbot/doc/TriggerSleepAction via #60

Assigned: myself

Tasks:

1. Verify if TSA continues ticking when F10 is pressed in Singleplayer /or/ Game paused in multiplayer
2. How it is affected by base game speed from .wgc
3. Lua: underlying impl uses coroutines?
4. (optional) check all other places where callback functions are accepted
5. Merge this text

pauses the current execution thread, sleeps for timeout of real-time seconds and resumes execution where this function was called. You may only use this inside trigger actions!

The [u]timeout[/u] timer has a granularity of 10Hz, this means you can only sleep in 100ms intervals at best (1000ms/10 = 100ms). [u]Timeout[/u] of 0 also sleeps for 100ms. [u]Timeouts[/u] -120 < x < 0 are the same as 0. [u]Timeouts[/u] <=-120 abort further execution.

[quote=WorldEdit help text]The duration of this wait is specified in real-time seconds.[/quote]
Therefore the game speed does not affect this timeout. Reforged (v1.32.10): Pausing the game also pauses the ticking of the timeout.

The behavior is similar to [url=https://www.lua.org/manual/5.3/manual.html#2.6]coroutines in Lua[/url], this principle is called [url=https://en.wikipedia.org/wiki/Cooperative_multitasking]cooperative multitasking[/url] where you hand off control of the execution thread and it is returned to you at a later time.

See: [jassdoc]PolledWait[/jassdoc] for sleeps in game-time seconds.

Example (Lua):
[code=lua]local secretWord = "please"
DisplayTextToPlayer(Player(0), 0, 0, "Current time is: ".. os.date())
TriggerSleepAction(10) -- sleeps for 10 seconds
DisplayTextToPlayer(Player(0), 0, 0, "After sleep the time is: ".. os.date() .." and the secret word is: ".. secretWord)[/code]