Merge pull request #318 from scratchcpp/refactor_event_loop

Refactor the event loop and loop blocks behavior

Author: adazem009

docs/Getting started.md

@@ -24,39 +24,5 @@ int main(int argc, char **argv) {
 The \link libscratchcpp::Project::run() run() \endlink method runs an event loop which stops after all scripts finish.
 
 For CLI project players, using \link libscratchcpp::Project::run() run() \endlink is enough. If you are developing
-a GUI project player and need to receive input events such as key presses, you'll need to implement your own event loop
-or use the one provided by the GUI framework.
-
-## GUI example (Qt)
-Qt provides an event loop which can be easily used to run frames with a specific frame rate.
-
-For example, a `Player` class which **inherits from QObject** can use a timer:
-```cpp
-#include <QObject>
-#include <scratchcpp/project.h>
-
-class Player : public QObject {
-    Q_OBJECT
-    public:
-        Player(QObject *parent = nullptr);
-        Player(const Player &) = delete; // Project is not copyable
-
-    protected:
-        void timerEvent(QTimerEvent *event) override;
-
-    private:
-        libscratchcpp::Project m_proj;
-}
-
-Player::Player(QObject *parent) {
-    m_proj.setFileName("/path/to/project.sb3");
-    m_proj.start();
-    int fps = 30;
-    startTimer(1000.0 / fps);
-}
-
-void Player::timerEvent(QTimerEvent *event) {
-    m_proj.frame();
-    event->accept();
-}
-```
+a GUI project player and need to receive input events such as key presses, you'll need to use \link libscratchcpp::Project::runEventLoop() runEventLoop() \endlink
+and run it in another thread (to keep the UI responsive).

include/scratchcpp/compiler.h

@@ -62,7 +62,6 @@ class LIBSCRATCHCPP_EXPORT Compiler
         void addProcedureArg(const std::string &procCode, const std::string &argName);
         void moveToSubstack(std::shared_ptr<Block> substack1, std::shared_ptr<Block> substack2, SubstackType type);
         void moveToSubstack(std::shared_ptr<Block> substack, SubstackType type);
-        void breakAtomicScript();
         void warp();
 
         Input *input(int id) const;

include/scratchcpp/iengine.h

@@ -42,17 +42,9 @@ class LIBSCRATCHCPP_EXPORT IEngine
          */
         virtual void compile() = 0;
 
-        /*!
-         * Runs a single frame.\n
-         * Use this if you want to use a custom event loop
-         * in your project player.
-         * \note Nothing will happen until start() is called.
-         */
-        virtual void frame() = 0;
-
         /*!
          * Calls all "when green flag clicked" blocks.
-         * \note Nothing will happen until run() or frame() is called.
+         * \note Nothing will happen until the event loop is started.
          */
         virtual void start() = 0;
 
@@ -85,13 +77,19 @@ class LIBSCRATCHCPP_EXPORT IEngine
         virtual void deinitClone(Sprite *clone) = 0;
 
         /*!
-         * Runs the event loop and calls "when green flag clicked" blocks.
+         * Calls and runs "when green flag clicked" blocks.
          * \note This function returns when all scripts finish.\n
-         * If you need to implement something advanced, such as a GUI with the
-         * green flag button, use frame().
+         * If you need an event loop that runs even after the project stops,
+         * use runEventLoop().
          */
         virtual void run() = 0;
 
+        /*!
+         * Runs the event loop. Call start() (from another thread) to start the project.
+         * \note This should be called from another thread in GUI project players to keep the UI responsive.
+         */
+        virtual void runEventLoop() = 0;
+
         /*! Returns true if the project is currently running. */
         virtual bool isRunning() const = 0;
 
@@ -159,23 +157,10 @@ class LIBSCRATCHCPP_EXPORT IEngine
         virtual bool broadcastByPtrRunning(Broadcast *broadcast, VirtualMachine *sourceScript) = 0;
 
         /*!
-         * Call this from a block implementation to force a "screen refresh".
+         * Call this from a block implementation to force a redraw (screen refresh).
          * \note This has no effect in "run without screen refresh" custom blocks.
          */
-        virtual void breakFrame() = 0;
-
-        /*! Returns true if breakFrame() was called. */
-        virtual bool breakingCurrentFrame() = 0;
-
-        /*!
-         * Call this from a block implementation to skip a frame and run the next frame immediately.\n
-         * The screen will be refreshed according to the frame rate.
-         * \note This also works in "run without screen refresh" custom blocks.
-         */
-        virtual void skipFrame() = 0;
-
-        /*! Call this from a block implementation to ignore calls to skipFrame() until the current frame ends. */
-        virtual void lockFrame() = 0;
+        virtual void requestRedraw() = 0;
 
         /*! Returns the timer of the project. */
         virtual ITimer *timer() const = 0;

include/scratchcpp/project.h

@@ -25,9 +25,9 @@ class LIBSCRATCHCPP_EXPORT Project
 
         bool load();
 
-        void frame();
         void start();
         void run();
+        void runEventLoop();
 
         const std::string &fileName() const;
         void setFileName(const std::string &newFileName);

include/scratchcpp/virtualmachine.h

@@ -79,7 +79,7 @@ enum Opcode
     OP_CALL_PROCEDURE, /*! Calls the procedure (custom block) with the index in the argument. */
     OP_ADD_ARG,        /*!< Adds a procedure (custom block) argument with the value from the last register. */
     OP_READ_ARG,       /*!< Reads the procedure (custom block) argument with the index in the argument and stores the value in the last register. */
-    OP_BREAK_ATOMIC,   /*!< Breaks current frame at the end of the loop. */
+    OP_BREAK_FRAME,    /*!< Breaks current frame at the end of the loop. */
     OP_WARP            /*! Runs the script without screen refresh. */
 };
 
@@ -131,7 +131,7 @@ class LIBSCRATCHCPP_EXPORT VirtualMachine
         void reset();
         void moveToLastCheckpoint();
 
-        void stop(bool savePos = true, bool breakAtomic = false, bool goBack = false);
+        void stop(bool savePos = true, bool breakFrame = false, bool goBack = false);
 
         bool atEnd() const;
 

src/blocks/controlblocks.cpp

@@ -139,6 +139,7 @@ void ControlBlocks::compileStop(Compiler *compiler)
     switch (option) {
         case StopAll:
             compiler->addFunctionCall(&stopAll);
+            compiler->addInstruction(vm::OP_HALT);
             break;
 
         case StopThisScript:
@@ -215,6 +216,8 @@ unsigned int ControlBlocks::startWait(VirtualMachine *vm)
 
     auto currentTime = clock->currentSteadyTime();
     m_timeMap[vm] = { currentTime, vm->getInput(0, 1)->toDouble() * 1000 };
+    vm->engine()->requestRedraw();
+
     return 1;
 }
 
@@ -230,8 +233,6 @@ unsigned int ControlBlocks::wait(VirtualMachine *vm)
         vm->stop(true, true, false);
     } else
         vm->stop(true, true, true);
-
-    vm->engine()->lockFrame();
     return 0;
 }
 

src/blocks/motionblocks.cpp

@@ -500,7 +500,6 @@ void MotionBlocks::continueGliding(VirtualMachine *vm)
         }
 
         vm->stop(true, true, true);
-        vm->engine()->lockFrame();
     }
 }
 

src/engine/compiler.cpp

@@ -27,7 +27,6 @@ void Compiler::init()
 
     impl->bytecode.clear();
     impl->procedurePrototype = nullptr;
-    impl->atomic = true;
     impl->warp = false;
 
     // Add start instruction
@@ -235,16 +234,6 @@ void Compiler::moveToSubstack(std::shared_ptr<Block> substack, SubstackType type
     moveToSubstack(substack, nullptr, type);
 }
 
-/*!
- * Adds the vm::OP_BREAK_ATOMIC instruction at the end of the current loop.
- * This can be used for example in motion blocks.
- * \note Nothing will happen if the script is set to run without screen refresh.
- */
-void Compiler::breakAtomicScript()
-{
-    impl->atomic = false;
-}
-
 /*! Makes current script run without screen refresh. */
 void Compiler::warp()
 {

src/engine/compiler_p.cpp

@@ -36,11 +36,10 @@ void CompilerPrivate::substackEnd()
     auto parent = substackTree.back();
     switch (parent.second) {
         case Compiler::SubstackType::Loop:
-            if (!atomic) {
-                if (!warp)
-                    addInstruction(OP_BREAK_ATOMIC);
-                atomic = true;
-            }
+            // Break the frame at the end of the loop so that other scripts can run within the frame
+            // This won't happen in "warp" scripts
+            if (!warp)
+                addInstruction(OP_BREAK_FRAME);
             addInstruction(OP_LOOP_END);
             break;
         case Compiler::SubstackType::IfStatement:

src/engine/compiler_p.h

@@ -36,7 +36,6 @@ struct CompilerPrivate
         std::vector<std::string> procedures;
         std::unordered_map<std::string, std::vector<std::string>> procedureArgs;
         BlockPrototype *procedurePrototype = nullptr;
-        bool atomic = true;
         bool warp = false;
 };