Add a frame event loop example

Author: fwsGonzo

engine/libtcc1.a

@@ -7,6 +7,18 @@ PUBLIC(void start())
 	print("Hello from Level 2!\n");
 	int value = gameplay_allowed_function(123);
 	print("Back in Level2! Got result value = ", value, "\n");
+
+	// Create a simple event loop
+	while (true) {
+		// Wait for a frame to complete
+		struct {
+			int frame = 0;
+		} frame_data;
+		Game::wait(frame_data);
+
+		// Do some work here, like updating game state, rendering, etc.
+		print("Frame ", frame_data.frame, " in Level2!\n");
+	}
 }
 
 int main() {}

engine/scripts/src/level2.cpp

@@ -67,17 +67,33 @@ int main()
 	}
 
 	strf::to(stdout)("...\n");
-	/* Ordinarily a game engine has a physics loop that ticks regularly,
-	   but we don't in this example. Instead we will just sleep until
-	   the next available timer. And resume the event loop in between. */
-	extern void timers_loop(std::function<void()>);
-	timers_loop(
-		[&]
-		{
-			/* This should run each engine tick instead. We are passing
-			   the maximum number of instructions that we allow it to use. */
-			events.resume(5'000);
-		});
+
+	/* Let's create a simple frame loop that depends on the guest
+	   waiting at a certain point in the code, with a pointer argument
+	   to frame data that is updated each frame. */
+	struct FrameData
+	{
+		int frame = 0;
+	};
+	/* When the guest pauses, the pointer to the frame data is the first argument (A0). */
+	FrameData* frame_data = level2.machine().memory.memarray<FrameData> (level2.machine().sysarg(0), 1);
+	/* Simulate 10 frames of gameplay. */
+	for (int i = 0; i < 10; ++i)
+	{
+		if (level2.getWaitingState() == 0) {
+			strf::to(stderr)("Level2 did not call Game::wait()!?\n");
+			return 1;
+		}
+		/* Set the data for the current frame.
+		   This is accessible to the guest program when it resumes. */
+		frame_data->frame = i;
+		/* Resume the level2 program, which unpauses the guest and continues
+		   execution until it loops around to the Game::wait() call again. */
+		if (!level2.resume(5'000)) {
+			strf::to(stderr)("Failed to resume level2!\n");
+			return 1;
+		}
+	}
 
 	/* Create an event that is callable. */
 	struct C

engine/src/main.cpp

@@ -255,6 +255,25 @@ struct Script
 	/// @return A wrapper managing the program-hosted objects. Can be moved.
 	template <typename T> GuestObjects<T> guest_alloc(size_t n = 1);
 
+	/// @brief Set the waiting state of the script.
+	/// This can be used to signal that the script is waiting in an event loop,
+	/// such as waiting for a frame to complete, or waiting for an event to occur.
+	/// @param state A user-defined state value, such as 0 for no wait, 1 for waiting for a frame, etc.
+	void setWaitingState(uint8_t state) noexcept
+	{
+		m_waiting_state = state;
+	}
+
+	/// @brief Get the current waiting state of the script.
+	/// This can be used to check if the script is waiting in an event loop,
+	/// such as waiting for a frame to complete, or waiting for an event to occur.
+	/// @return The current waiting state value, such as 0 for no wait, 1 for waiting for a frame, etc.
+	/// @note The waiting state is user-defined and can be any value.
+	uint8_t getWaitingState() const noexcept
+	{
+		return m_waiting_state;
+	}
+
 	/// @brief Start debugging with GDB right now. Only works on Linux.
 	/// @param message Message to print inside GDB.
 	/// @param one_up Always go one stack frame up? This can be used to leave a wrapper function.
@@ -322,6 +341,7 @@ struct Script
 	bool m_stdout			= true;
 	bool m_last_newline		= true;
 	int  m_budget_overruns	= 0;
+	uint8_t m_waiting_state = 0;
 	Script* m_remote_script = nullptr;
 	/// @brief Functions accessible when remote access is *strict*
 	std::unordered_set<gaddr_t> m_remote_access;

engine/src/script/script.hpp

@@ -85,9 +85,10 @@ APICALL(api_machine_hash)
 	machine.set_result(script(machine).hash());
 }
 
-APICALL(api_each_frame)
+APICALL(api_frame_wait)
 {
-	machine.set_result(-1);
+	script(machine).setWaitingState(1);
+	machine.stop(); // Pause here
 }
 
 APICALL(api_game_setting)
@@ -170,7 +171,7 @@ void Script::setup_syscall_interface()
 		{ECALL_DYNCALL, api_dyncall},
 		{ECALL_DYNARGS, api_dyncall_args},
 		{ECALL_MACHINE_HASH, api_machine_hash},
-		{ECALL_EACH_FRAME, api_each_frame},
+		{ECALL_FRAME_WAIT, api_frame_wait},
 
 		{ECALL_GAME_SETTING, api_game_setting},
 		{ECALL_GAME_EXIT, api_game_exit},

engine/src/script/script_syscalls.cpp

@@ -25,6 +25,12 @@ namespace api
 		static uint32_t current_machine();
 
 		static std::optional<intptr_t> setting(std::string_view);
+
+		/// @brief Enter a waiting state, and unpausing when the next frame is ready.
+		/// @tparam T 
+		/// @param data The frame data received from the host every frame.
+		template <typename T>
+		static void wait(T& data);
 	};
 
 	/** GUI **/

ext/libriscv

@@ -117,6 +117,13 @@ inline bool Game::is_debugging()
 	return sys_is_debug();
 }
 
+template <typename T>
+inline void Game::wait(T& data)
+{
+	sys_frame_wait(&data);
+}
+
+
 /** Timers **/
 
 using timer_callback = void (*)(int, void*);

programs/micro/api/api.h

@@ -9,7 +9,7 @@
 #define ECALL_DYNCALL        (GAME_API_BASE+4)
 #define ECALL_DYNARGS        (GAME_API_BASE+5)
 #define ECALL_MACHINE_HASH   (GAME_API_BASE+6)
-#define ECALL_EACH_FRAME     (GAME_API_BASE+7)
+#define ECALL_FRAME_WAIT     (GAME_API_BASE+7)
 #define ECALL_GAME_SETTING   (GAME_API_BASE+8)
 #define ECALL_GAME_EXIT      (GAME_API_BASE+9)
 

programs/micro/api/api_impl.h

@@ -28,3 +28,10 @@ asm(".global sys_write\n"
 "	li a7, " STRINGIFY(ECALL_WRITE) "\n"
 "	ecall\n"
 "   ret\n");
+
+asm(".global sys_frame_wait\n"
+	"sys_frame_wait:\n"
+	"	li a7, " STRINGIFY(ECALL_FRAME_WAIT) "\n"
+	"	ecall\n"
+	"   ret\n");
+