libscratchcpp
A library for C++ based Scratch project players
Loading...
Searching...
No Matches
libscratchcpp::IEngine Class Referenceabstract

The IEngine interface provides an API for running Scratch projects. More...

#include <scratchcpp/iengine.h>

Public Member Functions

virtual ~IEngine ()
 
virtual void clear ()=0
 
virtual void compile ()=0
 
virtual void start ()=0
 
virtual void stop ()=0
 
virtual ThreadstartScript (Block *topLevelBlock, Target *)=0
 
virtual void broadcast (int index, Thread *sender, bool wait)=0
 
virtual void broadcastByPtr (Broadcast *broadcast, Thread *sender, bool wait)=0
 
virtual void startBackdropScripts (Broadcast *broadcast, Thread *sender, bool wait)=0
 
virtual void stopScript (Thread *vm)=0
 
virtual void stopTarget (Target *target, Thread *exceptScript)=0
 
virtual void initClone (std::shared_ptr< Sprite > clone)=0
 
virtual void deinitClone (std::shared_ptr< Sprite > clone)=0
 
virtual void stopSounds ()=0
 
virtual double globalVolume () const =0
 
virtual void setGlobalVolume (double volume)=0
 
virtual void updateMonitors ()=0
 
virtual void step ()=0
 
virtual void run ()=0
 
virtual void runEventLoop ()=0
 
virtual void stopEventLoop ()=0
 
virtual sigslot::signal & aboutToRender ()=0
 
virtual sigslot::signal< Thread * > & threadAboutToStop ()=0
 
virtual sigslot::signal & stopped ()=0
 
virtual bool isRunning () const =0
 
virtual double fps () const =0
 
virtual void setFps (double fps)=0
 
virtual bool turboModeEnabled () const =0
 
virtual void setTurboModeEnabled (bool turboMode)=0
 
virtual bool keyPressed (const std::string &name) const =0
 
virtual void setKeyState (const std::string &name, bool pressed)=0
 
virtual void setKeyState (const KeyEvent &event, bool pressed)=0
 
virtual void setAnyKeyPressed (bool pressed)=0
 
virtual void mouseWheelUp ()=0
 
virtual void mouseWheelDown ()=0
 
virtual double mouseX () const =0
 
virtual void setMouseX (double x)=0
 
virtual double mouseY () const =0
 
virtual void setMouseY (double y)=0
 
virtual bool mousePressed () const =0
 
virtual void setMousePressed (bool pressed)=0
 
virtual void clickTarget (Target *target)=0
 
virtual const StringPtranswer () const =0
 
virtual unsigned int stageWidth () const =0
 
virtual void setStageWidth (unsigned int width)=0
 
virtual unsigned int stageHeight () const =0
 
virtual void setStageHeight (unsigned int height)=0
 
virtual int cloneLimit () const =0
 
virtual void setCloneLimit (int limit)=0
 
virtual int cloneCount () const =0
 
virtual bool spriteFencingEnabled () const =0
 
virtual void setSpriteFencingEnabled (bool enable)=0
 
virtual void requestRedraw ()=0
 
virtual ITimertimer () const =0
 
virtual void addCompileFunction (IExtension *extension, const std::string &opcode, BlockComp f)=0
 
virtual void addHatPredicateCompileFunction (IExtension *extension, const std::string &opcode, HatPredicateCompileFunc f)=0
 
virtual void addMonitorNameFunction (IExtension *extension, const std::string &opcode, MonitorNameFunc f)=0
 
virtual void addMonitorChangeFunction (IExtension *extension, const std::string &opcode, MonitorChangeFunc f)=0
 
virtual void addHatBlock (IExtension *extension, const std::string &opcode)=0
 
virtual const std::vector< std::shared_ptr< Broadcast > > & broadcasts () const =0
 
virtual void setBroadcasts (const std::vector< std::shared_ptr< Broadcast > > &broadcasts)=0
 
virtual std::shared_ptr< BroadcastbroadcastAt (int index) const =0
 
virtual std::vector< int > findBroadcasts (const std::string &broadcastName) const =0
 
virtual int findBroadcastById (const std::string &broadcastId) const =0
 
virtual void addWhenTouchingObjectScript (Block *hatBlock)=0
 
virtual void addGreenFlagScript (Block *hatBlock)=0
 
virtual void addBroadcastScript (Block *whenReceivedBlock, Field *field, Broadcast *broadcast)=0
 
virtual void addBackdropChangeScript (Block *hatBlock, Field *field)=0
 
virtual void addCloneInitScript (Block *hatBlock)=0
 
virtual void addKeyPressScript (Block *hatBlock, Field *field)=0
 
virtual void addTargetClickScript (Block *hatBlock)=0
 
virtual void addWhenGreaterThanScript (Block *hatBlock)=0
 
virtual const std::vector< std::shared_ptr< Target > > & targets () const =0
 
virtual void setTargets (const std::vector< std::shared_ptr< Target > > &newTargets)=0
 
virtual TargettargetAt (int index) const =0
 
virtual void getVisibleTargets (std::vector< Target * > &dst) const =0
 
virtual int findTarget (const std::string &targetName) const =0
 
virtual void moveDrawableToFront (Drawable *drawable)=0
 
virtual void moveDrawableToBack (Drawable *drawable)=0
 
virtual void moveDrawableForwardLayers (Drawable *drawable, int layers)=0
 
virtual void moveDrawableBackwardLayers (Drawable *drawable, int layers)=0
 
virtual void moveDrawableBehindOther (Drawable *drawable, Drawable *other)=0
 
virtual Stagestage () const =0
 
virtual const std::vector< std::shared_ptr< Monitor > > & monitors () const =0
 
virtual void setMonitors (const std::vector< std::shared_ptr< Monitor > > &newMonitors)=0
 
virtual MonitorcreateVariableMonitor (std::shared_ptr< Variable > var, const std::string &opcode, const std::string &varFieldName)=0
 
virtual MonitorcreateListMonitor (std::shared_ptr< List > list, const std::string &opcode, const std::string &listFieldName)=0
 
virtual sigslot::signal< Monitor * > & monitorAdded ()=0
 
virtual sigslot::signal< Monitor *, IMonitorHandler * > & monitorRemoved ()=0
 
virtual sigslot::signal< const std::string & > & questionAsked ()=0
 
virtual sigslot::signal & questionAborted ()=0
 
virtual sigslot::signal< const std::string & > & questionAnswered ()=0
 
virtual const std::vector< std::string > & extensions () const =0
 
virtual void setExtensions (const std::vector< std::string > &newExtensions)=0
 
virtual const std::unordered_map< Block *, std::shared_ptr< Script > > & scripts () const =0
 
virtual const std::string & userAgent () const =0
 
virtual void setUserAgent (const std::string &agent)=0
 
virtual const std::unordered_set< std::string > & unsupportedBlocks () const =0
 

Detailed Description

The IEngine interface provides an API for running Scratch projects.

This interface can be used to manipulate loaded Scratch projects.
To load a Scratch project, use the Project class.

Constructor & Destructor Documentation

◆ ~IEngine()

virtual libscratchcpp::IEngine::~IEngine ( )
inlinevirtual

Member Function Documentation

◆ aboutToRender()

virtual sigslot::signal & libscratchcpp::IEngine::aboutToRender ( )
pure virtual

Emits when rendering should occur.

◆ addBackdropChangeScript()

virtual void libscratchcpp::IEngine::addBackdropChangeScript ( Block * hatBlock,
Field * field )
pure virtual

Registers the backdrop change script.

◆ addBroadcastScript()

virtual void libscratchcpp::IEngine::addBroadcastScript ( Block * whenReceivedBlock,
Field * field,
Broadcast * broadcast )
pure virtual

Registers the broadcast script.

◆ addCloneInitScript()

virtual void libscratchcpp::IEngine::addCloneInitScript ( Block * hatBlock)
pure virtual

◆ addCompileFunction()

virtual void libscratchcpp::IEngine::addCompileFunction ( IExtension * extension,
const std::string & opcode,
BlockComp f )
pure virtual

Call this from IExtension::registerBlocks() to add a compile function to a block section.

See also
Extensions

◆ addGreenFlagScript()

virtual void libscratchcpp::IEngine::addGreenFlagScript ( Block * hatBlock)
pure virtual

Registers the "green flag" script.

◆ addHatBlock()

virtual void libscratchcpp::IEngine::addHatBlock ( IExtension * extension,
const std::string & opcode )
pure virtual

Call this from IExtension::registerBlocks() to add a hat block to a block section.

See also
Extensions

◆ addHatPredicateCompileFunction()

virtual void libscratchcpp::IEngine::addHatPredicateCompileFunction ( IExtension * extension,
const std::string & opcode,
HatPredicateCompileFunc f )
pure virtual

Call this from IExtension::registerBlocks() to add a hat block predicate compile function to a block section.

Note
This only works with edge-activated hats.
See also
Extensions

◆ addKeyPressScript()

virtual void libscratchcpp::IEngine::addKeyPressScript ( Block * hatBlock,
Field * field )
pure virtual

◆ addMonitorChangeFunction()

virtual void libscratchcpp::IEngine::addMonitorChangeFunction ( IExtension * extension,
const std::string & opcode,
MonitorChangeFunc f )
pure virtual

Call this from IExtension::registerBlocks() to add a monitor value change function to a block section.

See also
Extensions

◆ addMonitorNameFunction()

virtual void libscratchcpp::IEngine::addMonitorNameFunction ( IExtension * extension,
const std::string & opcode,
MonitorNameFunc f )
pure virtual

Call this from IExtension::registerBlocks() to add a monitor name function to a block section.

See also
Extensions

◆ addTargetClickScript()

virtual void libscratchcpp::IEngine::addTargetClickScript ( Block * hatBlock)
pure virtual

◆ addWhenGreaterThanScript()

virtual void libscratchcpp::IEngine::addWhenGreaterThanScript ( Block * hatBlock)
pure virtual

◆ addWhenTouchingObjectScript()

virtual void libscratchcpp::IEngine::addWhenTouchingObjectScript ( Block * hatBlock)
pure virtual

◆ answer()

virtual const StringPtr * libscratchcpp::IEngine::answer ( ) const
pure virtual

Returns the answer received from the user.

See also
questionAnswered()

◆ broadcast()

virtual void libscratchcpp::IEngine::broadcast ( int index,
Thread * sender,
bool wait )
pure virtual

Starts the scripts of the broadcast with the given index.

◆ broadcastAt()

virtual std::shared_ptr< Broadcast > libscratchcpp::IEngine::broadcastAt ( int index) const
pure virtual

Returns the broadcast at index.

◆ broadcastByPtr()

virtual void libscratchcpp::IEngine::broadcastByPtr ( Broadcast * broadcast,
Thread * sender,
bool wait )
pure virtual

Starts the scripts of the given broadcast.

◆ broadcasts()

virtual const std::vector< std::shared_ptr< Broadcast > > & libscratchcpp::IEngine::broadcasts ( ) const
pure virtual

Returns the list of broadcasts.

◆ clear()

virtual void libscratchcpp::IEngine::clear ( )
pure virtual

Clears the engine so that it can be used with another project.

◆ clickTarget()

virtual void libscratchcpp::IEngine::clickTarget ( Target * target)
pure virtual

Call this when a target is clicked.

◆ cloneCount()

virtual int libscratchcpp::IEngine::cloneCount ( ) const
pure virtual

Returns the current number of clones.

◆ cloneLimit()

virtual int libscratchcpp::IEngine::cloneLimit ( ) const
pure virtual

Returns the maximum number of clones (or -1 if the limit is disabled).

◆ compile()

virtual void libscratchcpp::IEngine::compile ( )
pure virtual

Compiles all scripts to bytecode.

See also
Compiler

◆ createListMonitor()

virtual Monitor * libscratchcpp::IEngine::createListMonitor ( std::shared_ptr< List > list,
const std::string & opcode,
const std::string & listFieldName )
pure virtual

Creates a monitor for the given list if it's missing and returns it.

◆ createVariableMonitor()

virtual Monitor * libscratchcpp::IEngine::createVariableMonitor ( std::shared_ptr< Variable > var,
const std::string & opcode,
const std::string & varFieldName )
pure virtual

Creates a monitor for the given variable if it's missing and returns it.

◆ deinitClone()

virtual void libscratchcpp::IEngine::deinitClone ( std::shared_ptr< Sprite > clone)
pure virtual

Automatically called from clones that are being deleted.

◆ extensions()

virtual const std::vector< std::string > & libscratchcpp::IEngine::extensions ( ) const
pure virtual

Returns the list of extension names.

◆ findBroadcastById()

virtual int libscratchcpp::IEngine::findBroadcastById ( const std::string & broadcastId) const
pure virtual

Returns the index of the broadcast with the given ID.

◆ findBroadcasts()

virtual std::vector< int > libscratchcpp::IEngine::findBroadcasts ( const std::string & broadcastName) const
pure virtual

Returns the list of indexes of the broadcasts with the given name (case insensitive).

◆ findTarget()

virtual int libscratchcpp::IEngine::findTarget ( const std::string & targetName) const
pure virtual

Returns the index of the target with the given name.

Note
Using "Stage" will return the index of the sprite with this name, or nullptr if it doesn't exist. Use the "_stage_" reserved name to get the stage, or use the stage() method.

◆ fps()

virtual double libscratchcpp::IEngine::fps ( ) const
pure virtual

Returns the framerate of the project.

◆ getVisibleTargets()

virtual void libscratchcpp::IEngine::getVisibleTargets ( std::vector< Target * > & dst) const
pure virtual

Gets visible targets sorted by layer order and stores them in the given vector.

◆ globalVolume()

virtual double libscratchcpp::IEngine::globalVolume ( ) const
pure virtual

Returns the global volume of all sounds (in %).

◆ initClone()

virtual void libscratchcpp::IEngine::initClone ( std::shared_ptr< Sprite > clone)
pure virtual

Calls the "when I start as a clone" blocks of the given sprite.

◆ isRunning()

virtual bool libscratchcpp::IEngine::isRunning ( ) const
pure virtual

Returns true if the project is currently running.

◆ keyPressed()

virtual bool libscratchcpp::IEngine::keyPressed ( const std::string & name) const
pure virtual

Returns true if the given key is pressed.

◆ monitorAdded()

virtual sigslot::signal< Monitor * > & libscratchcpp::IEngine::monitorAdded ( )
pure virtual

Emits when a monitor is added.

◆ monitorRemoved()

virtual sigslot::signal< Monitor *, IMonitorHandler * > & libscratchcpp::IEngine::monitorRemoved ( )
pure virtual

Emits when a monitor is removed.

◆ monitors()

virtual const std::vector< std::shared_ptr< Monitor > > & libscratchcpp::IEngine::monitors ( ) const
pure virtual

Returns the list of monitors.

◆ mousePressed()

virtual bool libscratchcpp::IEngine::mousePressed ( ) const
pure virtual

Returns true if mouse is pressed.

◆ mouseWheelDown()

virtual void libscratchcpp::IEngine::mouseWheelDown ( )
pure virtual

Starts "when down arrow key pressed" hats.

◆ mouseWheelUp()

virtual void libscratchcpp::IEngine::mouseWheelUp ( )
pure virtual

Starts "when up arrow key pressed" hats.

◆ mouseX()

virtual double libscratchcpp::IEngine::mouseX ( ) const
pure virtual

Returns the X coordinate of the mouse pointer.

◆ mouseY()

virtual double libscratchcpp::IEngine::mouseY ( ) const
pure virtual

Returns the Y coordinate of the mouse pointer.

◆ moveDrawableBackwardLayers()

virtual void libscratchcpp::IEngine::moveDrawableBackwardLayers ( Drawable * drawable,
int layers )
pure virtual

Moves the given sprite backward a number of layers.

◆ moveDrawableBehindOther()

virtual void libscratchcpp::IEngine::moveDrawableBehindOther ( Drawable * drawable,
Drawable * other )
pure virtual

Moves the given sprite behind some other sprite.

◆ moveDrawableForwardLayers()

virtual void libscratchcpp::IEngine::moveDrawableForwardLayers ( Drawable * drawable,
int layers )
pure virtual

Moves the given sprite forward a number of layers.

◆ moveDrawableToBack()

virtual void libscratchcpp::IEngine::moveDrawableToBack ( Drawable * drawable)
pure virtual

Moves the given sprite to the back layer.

◆ moveDrawableToFront()

virtual void libscratchcpp::IEngine::moveDrawableToFront ( Drawable * drawable)
pure virtual

Moves the given sprite to the front layer.

◆ questionAborted()

virtual sigslot::signal & libscratchcpp::IEngine::questionAborted ( )
pure virtual

Emits when the current question is aborted.

◆ questionAnswered()

virtual sigslot::signal< const std::string & > & libscratchcpp::IEngine::questionAnswered ( )
pure virtual

Emits when a question is answered.

◆ questionAsked()

virtual sigslot::signal< const std::string & > & libscratchcpp::IEngine::questionAsked ( )
pure virtual

Emits when a question is asked, for example using the 'ask and wait' block.

◆ requestRedraw()

virtual void libscratchcpp::IEngine::requestRedraw ( )
pure virtual

Call this from a block implementation to force a redraw (screen refresh).

Note
This has no effect in "run without screen refresh" custom blocks.

◆ run()

virtual void libscratchcpp::IEngine::run ( )
pure virtual

Calls and runs "when green flag clicked" blocks.

Note
This function returns when all scripts finish.
If you need an event loop that runs even after the project stops, use runEventLoop().

◆ runEventLoop()

virtual void libscratchcpp::IEngine::runEventLoop ( )
pure virtual

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.

◆ scripts()

virtual const std::unordered_map< Block *, std::shared_ptr< Script > > & libscratchcpp::IEngine::scripts ( ) const
pure virtual

Returns the map of scripts (each top level block has a Script object).

◆ setAnyKeyPressed()

virtual void libscratchcpp::IEngine::setAnyKeyPressed ( bool pressed)
pure virtual

Sets whether any key is pressed (use this for any key, even for unsupported keys).

◆ setBroadcasts()

virtual void libscratchcpp::IEngine::setBroadcasts ( const std::vector< std::shared_ptr< Broadcast > > & broadcasts)
pure virtual

Sets the list of broadcasts.

◆ setCloneLimit()

virtual void libscratchcpp::IEngine::setCloneLimit ( int limit)
pure virtual

Sets the maximum number of clones (use -1 or any negative number to disable the limit).

◆ setExtensions()

virtual void libscratchcpp::IEngine::setExtensions ( const std::vector< std::string > & newExtensions)
pure virtual

Sets the list of extension names.

◆ setFps()

virtual void libscratchcpp::IEngine::setFps ( double fps)
pure virtual

Sets the framerate of the project.

◆ setGlobalVolume()

virtual void libscratchcpp::IEngine::setGlobalVolume ( double volume)
pure virtual

Sets the global volume of all sounds (in %).

◆ setKeyState() [1/2]

virtual void libscratchcpp::IEngine::setKeyState ( const KeyEvent & event,
bool pressed )
pure virtual

Sets the state of the given key.

◆ setKeyState() [2/2]

virtual void libscratchcpp::IEngine::setKeyState ( const std::string & name,
bool pressed )
pure virtual

Sets the state of the key with the given name.

◆ setMonitors()

virtual void libscratchcpp::IEngine::setMonitors ( const std::vector< std::shared_ptr< Monitor > > & newMonitors)
pure virtual

Sets the list of monitors.

◆ setMousePressed()

virtual void libscratchcpp::IEngine::setMousePressed ( bool pressed)
pure virtual

Sets the pressed state of mouse.

◆ setMouseX()

virtual void libscratchcpp::IEngine::setMouseX ( double x)
pure virtual

Sets the X coordinate of the mouse pointer.

◆ setMouseY()

virtual void libscratchcpp::IEngine::setMouseY ( double y)
pure virtual

Sets the Y coordinate of the mouse pointer.

◆ setSpriteFencingEnabled()

virtual void libscratchcpp::IEngine::setSpriteFencingEnabled ( bool enable)
pure virtual

Toggles sprite fencing.

◆ setStageHeight()

virtual void libscratchcpp::IEngine::setStageHeight ( unsigned int height)
pure virtual

Sets the stage height.

◆ setStageWidth()

virtual void libscratchcpp::IEngine::setStageWidth ( unsigned int width)
pure virtual

Sets the stage width.

◆ setTargets()

virtual void libscratchcpp::IEngine::setTargets ( const std::vector< std::shared_ptr< Target > > & newTargets)
pure virtual

Sets the list of targets.

◆ setTurboModeEnabled()

virtual void libscratchcpp::IEngine::setTurboModeEnabled ( bool turboMode)
pure virtual

Sets whether turbo mode is enabled.

◆ setUserAgent()

virtual void libscratchcpp::IEngine::setUserAgent ( const std::string & agent)
pure virtual

Sets the user agent of the last person to edit the project.

◆ spriteFencingEnabled()

virtual bool libscratchcpp::IEngine::spriteFencingEnabled ( ) const
pure virtual

Returns true if sprite fencing is enabled.

◆ stage()

virtual Stage * libscratchcpp::IEngine::stage ( ) const
pure virtual

Returns the Stage.

◆ stageHeight()

virtual unsigned int libscratchcpp::IEngine::stageHeight ( ) const
pure virtual

Returns the stage height.

◆ stageWidth()

virtual unsigned int libscratchcpp::IEngine::stageWidth ( ) const
pure virtual

Returns the stage width.

◆ start()

virtual void libscratchcpp::IEngine::start ( )
pure virtual

Calls all "when green flag clicked" blocks.

Note
Nothing will happen until the event loop is started.

◆ startBackdropScripts()

virtual void libscratchcpp::IEngine::startBackdropScripts ( Broadcast * broadcast,
Thread * sender,
bool wait )
pure virtual

Starts the "when backdrop switches to" scripts for the given backdrop broadcast.

◆ startScript()

virtual Thread * libscratchcpp::IEngine::startScript ( Block * topLevelBlock,
Target *  )
pure virtual

Starts a script with the given top level block as the given Target (a sprite or the stage).

◆ step()

virtual void libscratchcpp::IEngine::step ( )
pure virtual

Steps all currently running threads. Use this to implement a custom event loop.

◆ stop()

virtual void libscratchcpp::IEngine::stop ( )
pure virtual

Stops all scripts.

◆ stopEventLoop()

virtual void libscratchcpp::IEngine::stopEventLoop ( )
pure virtual

Stops the event loop which is running in another thread.

◆ stopped()

virtual sigslot::signal & libscratchcpp::IEngine::stopped ( )
pure virtual

Emits when the project is stopped by calling stop().

◆ stopScript()

virtual void libscratchcpp::IEngine::stopScript ( Thread * vm)
pure virtual

Stops the given script.

◆ stopSounds()

virtual void libscratchcpp::IEngine::stopSounds ( )
pure virtual

Stops all currently playing sounds.

◆ stopTarget()

virtual void libscratchcpp::IEngine::stopTarget ( Target * target,
Thread * exceptScript )
pure virtual

Stops all scripts in the given target.

Parameters
[in]targetThe Target to stop.
[in]exceptScriptSets this parameter to stop all scripts except the given script.

◆ targetAt()

virtual Target * libscratchcpp::IEngine::targetAt ( int index) const
pure virtual

Returns the target at index.

◆ targets()

virtual const std::vector< std::shared_ptr< Target > > & libscratchcpp::IEngine::targets ( ) const
pure virtual

Returns the list of targets.

◆ threadAboutToStop()

virtual sigslot::signal< Thread * > & libscratchcpp::IEngine::threadAboutToStop ( )
pure virtual

Emits when a script is about to stop.

◆ timer()

virtual ITimer * libscratchcpp::IEngine::timer ( ) const
pure virtual

Returns the timer of the project.

◆ turboModeEnabled()

virtual bool libscratchcpp::IEngine::turboModeEnabled ( ) const
pure virtual

Returns true if turbo mode is enabled.

◆ unsupportedBlocks()

virtual const std::unordered_set< std::string > & libscratchcpp::IEngine::unsupportedBlocks ( ) const
pure virtual

Returns the unsupported block opcodes which were found when compiling.

◆ updateMonitors()

virtual void libscratchcpp::IEngine::updateMonitors ( )
pure virtual

Updates the values of stage monitors.

◆ userAgent()

virtual const std::string & libscratchcpp::IEngine::userAgent ( ) const
pure virtual

Returns the user agent of the last person to edit the project.


The documentation for this class was generated from the following file: