Browse Source

Clarify AsyncScript usage

AsyncScript is still a bit too confusing, just clarifying some of its quirks.
Eideren 1 year ago
parent
commit
ce7854ec1f
1 changed files with 17 additions and 5 deletions
  1. 17 5
      en/manual/scripts/types-of-script.md

+ 17 - 5
en/manual/scripts/types-of-script.md

@@ -59,14 +59,26 @@ public class SampleAsyncScript : AsyncScript
 	public override async Task Execute() 
 	public override async Task Execute() 
 	{
 	{
 		// The initialization code should come here, if necessary
 		// The initialization code should come here, if necessary
+		// This method starts running on the main thread
 		
 		
 		while (Game.IsRunning) // loop until the game ends (optional depending on the script)
 		while (Game.IsRunning) // loop until the game ends (optional depending on the script)
 		{
 		{
-			await MyEvent;
+			// We're still on the main thread
 
 
-			// Do some stuff
-			
-			await Script.NextFrame(); // wait for the next frame (optional depending on the script)
+			// Task.Run will pause the execution of this method until the task is completed,
+			// while that's going on, the game will continue running, it will display new frames and process inputs appropriately
+			var lobbies = await Task.Run(() => GetMultiplayerLobbies());
+
+			// After awaiting a task, the thread the method runs on will have changed, this method now runs on a thread pool thread instead of the main thread
+			// You can manipulate the data returned by the task here if needed
+			// But if you want to interact with the engine safely, you have to make sure the method runs on the main thread
+
+			// await Script.NextFrame() yields execution of this method to the main thread, meaning that this method is paused, and once the main thread processes the next frame,
+			// it will pick that method up and run it
+			await Script.NextFrame();
+			// So after this call, this method is back on the main thread
+
+			// You can now safely interact with the engine's systems by displaying the lobbies retrieved above in a UI for example
 		}
 		}
 	}
 	}
 }
 }
@@ -80,4 +92,4 @@ public class SampleAsyncScript : AsyncScript
 * [Scheduling and priorities](scheduling-and-priorities.md)
 * [Scheduling and priorities](scheduling-and-priorities.md)
 * [Events](events.md)
 * [Events](events.md)
 * [Debugging](debugging.md)
 * [Debugging](debugging.md)
-* [Preprocessor variables](preprocessor-variables.md)
+* [Preprocessor variables](preprocessor-variables.md)