Package org.openpatch.scratch

Class Stage

java.lang.Object
org.openpatch.scratch.Stage
Direct Known Subclasses:
VisualProbe
public class Stage extends Object
The Stage class represents a stage where various elements such as sprites, texts, pens, and backdrops can be added and manipulated. It provides methods to manage these elements, handle events, and control the stage's appearance and behavior.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Stage()
    Constructs a new Stage with default dimensions.
    Stage(int width, int height)
    Constructs a new Stage with the specified width and height.
    Stage(int width, int height, String assets)
    Constructs a new Stage with the specified width, height, and assets path.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    add(Pen pen)
    Adds a Pen object to the stage.
    void
    add(Sprite sprite)
    Adds a sprite to the stage.
    void
    add(Text text)
    Add a text object to the stage
    void
    addBackdrop(String name)
    Add one of the backdrops that ship with Scratch for Java to the stage.
    void
    addBackdrop(String name, String imagePath)
    Add a backdrop to the stage.
    void
    addBackdrop(String name, String imagePath, boolean stretch)
    Add a backdrop to the stage.
    void
    addSound(String name)
    Add one of the sounds that ship with Scratch for Java to the stage.
    void
    addSound(String name, String soundPath)
    Add a sound to the stage.
    void
    ask(String question)
    Asks a question and waits for an answer to be typed in.
    void
    broadcast(String message)
    Broadcasts a message to all sprites in the stage.
    void
    changeColor(double h)
    Changes the background color by adding a step to the hue value.
    void
    changeTint(double step)
    Changes the colour the backdrop is tinted with by a step.
    void
    changeTransparency(double step)
    Changes how see-through the backdrop is by a step.
    void
    changeVolume(double step)
    Makes every sound of this stage louder or quieter.
    <T extends Sprite>
    int
    count(Class<T> c)
    Returns the number of sprites of the specified class.
    void
    debug(Object... values)
    Prints a debug message to stdout when debug mode is enabled.
    void
    display(String text)
    Displays the given text on the stage.
    void
    display(String text, int millis)
    Displays the given text on the screen for a specified duration.
    void
    eraseAll()
    Erases all lines on the pen layer.
    void
    exit()
    Close the window and therefore the whole application.
    <T extends Sprite>
    List<T>
    find(Class<T> c)
    Find sprites of a given class.
    List<Sprite>
    getAll()
    Retrieves a list of all sprites in the current stage.
    String
    getAnswer()
    Returns the last answer that was typed in.
    Camera
    getCamera()
    Retrieves the current camera instance associated with this stage.
    Color
    getColor()
    Returns the current color of the stage.
    int
    getCurrentBackdropIndex()
    Returns the current backdrop index
    String
    getCurrentBackdropName()
    Returns the current backdrop name
    double
    getDeltaTime()
    Gets the seconds passed since the last frame.
    double
    getFrameRate()
    Get the frame rate of the application.
    int
    getHeight()
    Return the height of the current costume or the pen size, when no costume is available.
    Vector2
    getMouse()
    Returns the current position of the mouse cursor as a Vector2
    double
    getMouseX()
    Returns the current x-position of the mouse cursor
    double
    getMouseY()
    Returns the current y-position of the mouse cursor
    Pixels
    getPixels()
    Returns the colours of everything this stage has drawn.
    Shaders
    getShaders()
    Returns the shaders of this stage.
    Sorting
    getSorting()
    Returns the order in which the sprites of this stage are drawn.
    Timer
    getTimer()
    Returns the timer
    Timer
    getTimer(String name)
    Returns a timer by name
    double
    getVolume()
    Returns how loud the sounds of this stage play.
    int
    getWidth()
    Return the width of the current costume or the pen size, when no costume is available.
    boolean
    isAsking()
    Checks whether a question is on screen and still waiting for an answer.
    boolean
    isDebug()
    Checks if the application is in debug mode.
    boolean
    isKeyPressed(KeyCode keyCode)
    Returns true if the key is pressed
    boolean
    isMouseDown()
    Returns true is the mouse button is down
    boolean
    isSoundPlaying(String name)
    Returns true if the sound if playing
    void
    nextBackdrop()
    Switch to the next backdrop.
    int
    pickRandom(int from, int to)
    Returns a random integer between the specified range (inclusive).
    void
    playSound(String name)
    Plays a sound.
    void
    previousBackdrop()
    Switch to the previous backdrop.
    void
    randomBackdrop()
    Switch to a random backdrop.
    void
    remove(Class<? extends Sprite> c)
    Removes all sprites of the specified class from the stage.
    void
    remove(Pen pen)
    Removes the specified pen from the stage.
    void
    remove(Sprite sprite)
    Removes the specified sprite from the stage.
    void
    remove(Text text)
    Removes the specified text from the stage.
    void
    removeAll()
    Removes all elements from the stage.
    void
    run()
    Executes the main logic of the stage.
    void
    setColor(double h)
    Sets the background color via a hue value
    void
    setColor(double r, double g, double b)
    Sets the background color via a rgb value
    void
    setColor(Color c)
    Sets the color of the stage.
    void
    setCursor(String path)
    Sets the cursor image for the stage.
    void
    setCursor(String path, int x, int y)
    Sets the cursor image and its active spot coordinates.
    void
    setDebug(boolean debug)
    Enables or disables the debug mode for the application.
    void
    setTint(double h)
    Sets the colour the backdrop is tinted with, as a hue.
    void
    setTint(double r, double g, double b)
    Sets the colour the backdrop is tinted with.
    void
    setTransparency(double transparency)
    Sets how see-through the backdrop is, as Scratch's ghost effect does: 0 is the solid backdrop you start with and 100 is invisible.
    void
    setVolume(double percent)
    Sets how loud every sound of this stage plays.
    void
    stopAllSounds()
    Stops the playing of all sounds of the stage.
    void
    stopSound(String name)
    Stops the playing of the sound with the given name
    void
    switchBackdrop(String name)
    Switch to a backdrop by name.
    void
    wait(int millis)
    Stop the execution of the whole applications for the given milliseconds.
    void
    waitUntil(BooleanSupplier condition)
    Waits until something becomes true, then carries on.
    void
    whenBackdropSwitches(String name)
    This method is called when the backdrop switches to the specified name.
    void
    whenIReceive(String message)
    This method is called when a specific message is received.
    void
    whenKeyPressed(KeyCode keyCode)
    This method is called when a key is pressed.
    void
    whenKeyReleased(KeyCode keyCode)
    This method is called when a key is released.
    void
    whenMouseClicked(MouseCode mouseEvent)
    This method is called when a mouse click event occurs.
    void
    whenMouseWheelMoved(int steps)
    This method is called when the mouse wheel is moved.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • Stage

      public Stage()
      Constructs a new Stage with default dimensions. The default width is 480 pixels and the default height is 360 pixels.

    • Stage

      public Stage(int width, int height)
      Constructs a new Stage with the specified width and height.
      Parameters:
      width - the width of the stage
      height - the height of the stage

    • Stage

      public Stage(int width, int height, String assets)
      Constructs a new Stage with the specified width, height, and assets path.
      Parameters:
      width - the width of the stage
      height - the height of the stage
      assets - the path to the assets directory

  • Method Details

    • getSorting

      public Sorting getSorting()
      Returns the order in which the sprites of this stage are drawn.

      Example usage: 

      
 this.getSorting().byY();
      Returns:
      the sorting

    • getPixels

      public Pixels getPixels()
      Returns the colours of everything this stage has drawn.

      Example usage: 

      
 int[] colours = this.getPixels().main();
      Returns:
      the pixels

    • getShaders

      public Shaders getShaders()
      Returns the shaders of this stage. Shader handling lives behind this one method so that it does not crowd the everyday API.

      Example usage: 

      
 this.getShaders().add("blur", "blur.frag", null);
 this.getShaders().switchTo("blur");
      Returns:
      the shaders

    • setDebug

      public void setDebug(boolean debug)
      Enables or disables the debug mode for the application.
      Parameters:
      debug - a boolean value where true enables debug mode and false disables it.

    • isDebug

      public boolean isDebug()
      Checks if the application is in debug mode.
      Returns:
      true if the application is in debug mode, false otherwise.

    • debug

      public void debug(Object... values)
      Prints a debug message to stdout when debug mode is enabled. The message is prefixed with the stage's class name so you can tell which stage it came from.

      Example: 

      
 this.debug("score =", score, "lives =", lives);
 // prints: [MyStage] score = 5 lives = 3
      Parameters:
      values - one or more values to print

    • add

      public void add(Sprite sprite)
      Adds a sprite to the stage. Sprites are drawn in the order they were added, so a sprite added later is drawn on top of one added earlier.
      Parameters:
      sprite - the sprite to add

    • add

      public void add(Text text)
      Add a text object to the stage
      Parameters:
      text - a text

    • add

      public void add(Pen pen)
      Adds a Pen object to the stage.
      Parameters:
      pen - the Pen object to be added to the stage

    • getAll

      public List<Sprite> getAll()
      Retrieves a list of all sprites in the current stage.
      Returns:
      a list containing all sp

    • remove

      public void remove(Sprite sprite)
      Removes the specified sprite from the stage.
      Parameters:
      sprite - the sprite to be removed

    • remove

      public void remove(Pen pen)
      Removes the specified pen from the stage.
      Parameters:
      pen - the pen to be removed

    • remove

      public void remove(Text text)
      Removes the specified text from the stage.
      Parameters:
      text - the text to be removed

    • removeAll

      public void removeAll()
      Removes all elements from the stage.

    • remove

      public void remove(Class<? extends Sprite> c)
      Removes all sprites of the specified class from the stage.
      Parameters:
      c - the class of the sprites to remove

    • find

      public <T extends Sprite> List<T> find(Class<T> c)
      Find sprites of a given class.
      Parameters:
      c - Class

    • count

      public <T extends Sprite> int count(Class<T> c)
      Returns the number of sprites of the specified class.
      Parameters:
      c - the class of the sprites to count
      Returns:
      the number of sprites of the specified class

    • addBackdrop

      public void addBackdrop(String name, String imagePath, boolean stretch)
      Add a backdrop to the stage. If a backdrop with the received name already exists do nothing.
      Parameters:
      name - a unique name
      imagePath - a image path, or the name of a built-in sprite such as "bg_castle"
      stretch - stretch image to window size

    • addBackdrop

      public void addBackdrop(String name, String imagePath)
      Add a backdrop to the stage. If a backdrop with the received name already exists do nothing.
      Parameters:
      name - a unique name
      imagePath - a image path, or the name of a built-in sprite such as "bg_castle"

    • addBackdrop

      public void addBackdrop(String name)
      Add one of the backdrops that ship with Scratch for Java to the stage. The backdrop gets the same name as the built-in sprite. If a backdrop with that name already exists do nothing.

      Example usage: 

      
 this.addBackdrop("bg_castle");
      Parameters:
      name - the name of a built-in sprite, for example "bg_castle". Add the sheet in front of the name, for example "platformer/grass", if the same name exists on several sheets.

    • switchBackdrop

      public void switchBackdrop(String name)
      Switch to a backdrop by name.
      Parameters:
      name - the name of a backdrop
      Scratch Block:
      switch backdrop to [name v]

    • whenBackdropSwitches

      public void whenBackdropSwitches(String name)
      This method is called when the backdrop switches to the specified name. Override this method to add custom behavior.
      Parameters:
      name - the name of the backdrop to switch to

    • nextBackdrop

      public void nextBackdrop()
      Switch to the next backdrop.
      Scratch Block:
      next backdrop

    • previousBackdrop

      public void previousBackdrop()
      Switch to the previous backdrop.
      Scratch Block:
      switch backdrop to [previous backdrop v]

    • randomBackdrop

      public void randomBackdrop()
      Switch to a random backdrop.
      Scratch Block:
      switch backdrop to [random backdrop v]

    • getCurrentBackdropName

      public String getCurrentBackdropName()
      Returns the current backdrop name
      Returns:
      a backdrop name
      Scratch Block:
      (backdrop [name v])

    • getCurrentBackdropIndex

      public int getCurrentBackdropIndex()
      Returns the current backdrop index
      Returns:
      a backdrop index
      Scratch Block:
      (backdrop [number v])

    • eraseAll

      public void eraseAll()
      Erases all lines on the pen layer.
      Scratch Block:
      erase all

    • addSound

      public void addSound(String name, String soundPath)
      Add a sound to the stage. If a sound with the received name already exists do nothing.
      Parameters:
      name - a unique name
      soundPath - a sound path, or the name of a built-in sound such as "footstep_carpet_000"

    • addSound

      public void addSound(String name)
      Add one of the sounds that ship with Scratch for Java to the stage. The sound gets the same name as the built-in sound. If a sound with that name already exists do nothing.

      Example usage: 

      
 this.addSound("footstep_carpet_000");
      Parameters:
      name - the name of a built-in sound, for example "footstep_carpet_000"

    • playSound

      public void playSound(String name)
      Plays a sound.
      Parameters:
      name - the sound name
      Scratch Block:
      start sound [name v]

    • stopAllSounds

      public void stopAllSounds()
      Stops the playing of all sounds of the stage.
      Scratch Block:
      stop all sounds

    • stopSound

      public void stopSound(String name)
      Stops the playing of the sound with the given name
      Parameters:
      name - Name of the sound

    • isSoundPlaying

      public boolean isSoundPlaying(String name)
      Returns true if the sound if playing
      Returns:
      playing

    • setColor

      public void setColor(double h)
      Sets the background color via a hue value
      Parameters:
      h - a hue value [0...255]

    • setColor

      public void setColor(double r, double g, double b)
      Sets the background color via a rgb value
      Parameters:
      r - a red value [0...255]
      g - a green value [0...255]
      b - a blue value [0...255]

    • getColor

      public Color getColor()
      Returns the current color of the stage.
      Returns:
      the current color

    • setColor

      public void setColor(Color c)
      Sets the color of the stage.
      Parameters:
      c - the new color to be set
      See Also:

    • changeColor

      public void changeColor(double h)
      Changes the background color by adding a step to the hue value.
      Parameters:
      h - a step value

    • setTint

      public void setTint(double r, double g, double b)
      Sets the colour the backdrop is tinted with.
      Parameters:
      r - a red value [0...255]
      g - a green value [0...255]
      b - a blue value [0...255]
      See Also:

    • setTint

      public void setTint(double h)
      Sets the colour the backdrop is tinted with, as a hue.
      See Also:
      Scratch Block:
      set [color v] effect to (h)

    • changeTint

      public void changeTint(double step)
      Changes the colour the backdrop is tinted with by a step.
      Parameters:
      step - a step value
      See Also:
      Scratch Block:
      change [color v] effect by (step)

    • setTransparency

      public void setTransparency(double transparency)
      Sets how see-through the backdrop is, as Scratch's ghost effect does: 0 is the solid backdrop you start with and 100 is invisible.
      Parameters:
      transparency - [0...100], 0 solid and 100 invisible
      See Also:
      Scratch Block:
      set [ghost v] effect to (transparency)

    • changeTransparency

      public void changeTransparency(double step)
      Changes how see-through the backdrop is by a step. A positive step fades it out, a negative one brings it back.
      Parameters:
      step - a step value
      See Also:
      Scratch Block:
      change [ghost v] effect by (step)

    • getWidth

      public int getWidth()
      Return the width of the current costume or the pen size, when no costume is available.
      Returns:
      the width of the sprite

    • getHeight

      public int getHeight()
      Return the height of the current costume or the pen size, when no costume is available.
      Returns:
      the height of the sprite

    • getTimer

      public Timer getTimer()
      Returns the timer
      Returns:
      the timer
      Scratch Block:
      (timer)

    • getTimer

      public Timer getTimer(String name)
      Returns a timer by name
      Parameters:
      name - a name
      Returns:
      the timer

    • whenMouseClicked

      public void whenMouseClicked(MouseCode mouseEvent)
      This method is called when a mouse click event occurs. Overwrite this method to add custom behavior.
      Parameters:
      mouseEvent - The mouse event that triggered this method.
      Scratch Block:
      when stage clicked

    • whenMouseWheelMoved

      public void whenMouseWheelMoved(int steps)
      This method is called when the mouse wheel is moved. Overwrite this method to add custom behavior.
      Parameters:
      steps - the number of steps the mouse wheel has moved. Positive values indicate movement away from the user, while negative values indicate movement towards the user.

    • getMouseX

      public double getMouseX()
      Returns the current x-position of the mouse cursor
      Returns:
      x-position
      Scratch Block:
      (mouse x)

    • getMouseY

      public double getMouseY()
      Returns the current y-position of the mouse cursor
      Returns:
      y-position
      Scratch Block:
      (mouse y)

    • getMouse

      public Vector2 getMouse()
      Returns the current position of the mouse cursor as a Vector2
      Returns:
      mouse position

    • isMouseDown

      public boolean isMouseDown()
      Returns true is the mouse button is down
      Returns:
      mouse button down
      Scratch Block:
      <mouse down?>

    • whenKeyPressed

      public void whenKeyPressed(KeyCode keyCode)
      This method is called when a key is pressed. Override this method to add custom behavior.
      Parameters:
      keyCode - the key that was pressed
      Scratch Block:
      when [space v] key pressed

    • whenKeyReleased

      public void whenKeyReleased(KeyCode keyCode)
      This method is called when a key is released. Override this method to add custom behavior.
      Parameters:
      keyCode - the key that was released

    • isKeyPressed

      public boolean isKeyPressed(KeyCode keyCode)
      Returns true if the key is pressed
      Parameters:
      keyCode - a key
      Returns:
      key pressed
      Scratch Block:
      <key [space v] pressed?>

    • getDeltaTime

      public double getDeltaTime()
      Gets the seconds passed since the last frame.
      Returns:
      secons since last frame

    • pickRandom

      public int pickRandom(int from, int to)
      Returns a random integer between the specified range (inclusive).
      Parameters:
      from - the lower bound of the range (inclusive)
      to - the upper bound of the range (inclusive)
      Returns:
      a random integer between from and to (inclusive)
      Scratch Block:
      (pick random (from) to (to))

    • display

      public void display(String text)
      Displays the given text on the stage.
      Parameters:
      text - the text to be displayed

    • display

      public void display(String text, int millis)
      Displays the given text on the screen for a specified duration.
      Parameters:
      text - The text to be displayed.
      millis - The duration in milliseconds for which the text will be displayed.

    • setVolume

      public void setVolume(double percent)
      Sets how loud every sound of this stage plays.
      Parameters:
      percent - 0 for silent, 100 for full volume
      Scratch Block:
      set volume to (percent) %

    • changeVolume

      public void changeVolume(double step)
      Makes every sound of this stage louder or quieter.
      Parameters:
      step - how much to add to the volume, in percent
      Scratch Block:
      change volume by (step)

    • getVolume

      public double getVolume()
      Returns how loud the sounds of this stage play.
      Returns:
      the volume, from 0 to 100
      Scratch Block:
      (volume)

    • ask

      public void ask(String question)
      Asks a question and waits for an answer to be typed in. A box appears at the bottom of the stage; whatever is typed goes into it until Enter is pressed.

      Unlike Scratch, this does not pause anything. Your `run()` keeps being called while the question is on screen, so check isAsking() or wait for getAnswer() to change: 

      
 public void run() {
   if (!this.isAsking() && this.getAnswer().isEmpty()) {
     this.ask("What is your name?");
   }
   if (!this.getAnswer().isEmpty()) {
     this.display("Hello " + this.getAnswer() + "!");
   }
 }
      Parameters:
      question - the question to show
      Scratch Block:
      ask [question] and wait

    • getAnswer

      public String getAnswer()
      Returns the last answer that was typed in.
      Returns:
      the answer, or an empty string if nothing has been answered yet
      Scratch Block:
      (answer)

    • isAsking

      public boolean isAsking()
      Checks whether a question is on screen and still waiting for an answer.
      Returns:
      true while a question is waiting

    • broadcast

      public void broadcast(String message)
      Broadcasts a message to all sprites in the stage. Each sprite will execute its `whenIReceive` method with the given message.
      Parameters:
      message - The message to broadcast to all sprites.
      Scratch Block:
      broadcast [message v]

    • whenIReceive

      public void whenIReceive(String message)
      This method is called when a specific message is received. Override this method to add custom behavior.
      Parameters:
      message - The message that triggers this method.
      Scratch Block:
      when I receive [message v]

    • setCursor

      public void setCursor(String path)
      Sets the cursor image for the stage.
      Parameters:
      path - a path to an image file, or the name of a built-in sprite

    • setCursor

      public void setCursor(String path, int x, int y)
      Sets the cursor image and its active spot coordinates.
      Parameters:
      path - a path to an image file, or the name of a built-in sprite
      x - the x-coordinate of the cursor's active spot
      y - the y-coordinate of the cursor's active spot

    • getCamera

      public Camera getCamera()
      Retrieves the current camera instance associated with this stage.
      Returns:
      the current Camera object.

    • wait

      public void wait(int millis)
      Stop the execution of the whole applications for the given milliseconds.
      Parameters:
      millis - Milliseconds
      Scratch Block:
      wait (millis) seconds

    • waitUntil

      public void waitUntil(BooleanSupplier condition)
      Waits until something becomes true, then carries on.

      Like wait(int) this holds up the code that calls it, not the whole program: sprites keep running and the stage keeps drawing while it waits. That makes it useful for setting a scene up in a constructor, and a bad idea inside `run()`, which is called once per frame and should return quickly. 

      
 this.ask("What is your name?");
 this.waitUntil(() -> !this.isAsking());
 this.display("Hello " + this.getAnswer() + "!");
      Parameters:
      condition - checked over and over until it is true
      Scratch Block:
      wait until <condition>

    • getFrameRate

      public double getFrameRate()
      Get the frame rate of the application.
      Returns:
      the frame rate

    • run

      public void run()
      Executes the main logic of the stage. This method should be overridden by subclasses to define the specific behavior of the stage.

    • exit

      public void exit()
      Close the window and therefore the whole application.