Class Stage

java.lang.Object
org.openpatch.scratch.Stage
public class Stage extends Object
A stage: one screen of a program, with its backdrops, sprites, texts and pens, and code that runs every tick in run(). The window shows one stage at a time (window.setStage(new MyStage())). 
public class MyStage extends Stage {
  public MyStage() {
    this.addBackdrop("forest", "assets/forest.png");
    this.add(new Cat());
  }
}

A stage needs the window to exist, since the window sets its size: create the window first.

  • Constructor Details

    • Stage

      public Stage()
      A stage the size of the window.

  • Method Details

    • getWidth

      public int getWidth()
      Returns:
      the stage's width in stage pixels

    • getHeight

      public int getHeight()
      Returns:
      the stage's height in stage pixels

    • getShaders

      public Shaders getShaders()
      Returns:
      the stage's shaders, applied to the picture of its world layers

    • extension

      public <T> T extension(Class<T> type, Supplier<T> factory)
      An extension's state for this stage, made on first use. For extensions, not for learner code.
      Type Parameters:
      T - the state
      Parameters:
      type - the state's class
      factory - makes it
      Returns:
      the stage's one instance

    • getCamera

      public Camera getCamera()
      Returns:
      the stage's camera

    • debug

      public void debug(Object... values)
      Prints values for debugging, but only while debug mode is on.
      Parameters:
      values - what to print

    • showVariable

      public void showVariable(String name, Supplier<?> value)
      Shows a variable in a box at the top left of the stage, like a Scratch monitor; its value is read every frame. 
      this.showVariable("score", () -> this.score);
      Parameters:
      name - the label
      value - gives the value to show
      Scratch Block:
      show variable [name v]

    • hideVariable

      public void hideVariable(String name)
      Parameters:
      name - the label of a variable to hide again
      Scratch Block:
      hide variable [name v]

    • add

      public void add(Sprite sprite)
      Adds a sprite, in front of the sprites of its layer. A sprite can only be on one stage; it leaves the old one.
      Parameters:
      sprite - the sprite

    • add

      public void add(Pen pen)
      Adds a pen of its own.
      Parameters:
      pen - the pen

    • add

      public void add(Text text)
      Adds a text of its own.
      Parameters:
      text - the text

    • remove

      public void remove(Text text)
      Parameters:
      text - a text of its own to remove

    • remove

      public void remove(Sprite sprite)
      Removes a sprite.
      Parameters:
      sprite - the sprite

    • remove

      public void remove(Pen pen)
      Parameters:
      pen - a pen of its own to remove

    • remove

      public void remove(Class<? extends Sprite> type)
      Removes every sprite of a class (subclasses included).
      Parameters:
      type - the class

    • removeAll

      public void removeAll()
      Removes every sprite, text and pen: an empty stage (backdrops and what was drawn stay).

    • getAll

      public List<Sprite> getAll()
      Returns:
      every sprite on the stage, back to front, layer by layer

    • find

      public <T extends Sprite> List<T> find(Class<T> type)
      Type Parameters:
      T - the class
      Parameters:
      type - a class of sprites
      Returns:
      every sprite of that class (subclasses included), back to front

    • count

      public <T extends Sprite> int count(Class<T> type)
      Type Parameters:
      T - the class
      Parameters:
      type - a class of sprites
      Returns:
      how many sprites of that class are on the stage

    • sortByY

      public void sortByY()
      Draws and runs the sprites of each layer sorted by their y position: lower sprites in front, as in a top-down game. Applies from the next tick on, until stopSorting().

    • sortBy

      public void sortBy(Comparator<? super Sprite> comparator)
      Draws and runs the sprites of each layer in the order a comparator gives, back to front.
      Parameters:
      comparator - the order

    • stopSorting

      public void stopSorting()
      Keeps the order the sprites have now and stops sorting them.

    • addBackdrop

      public void addBackdrop(String name, String imagePath)
      Adds a backdrop. The first one added is shown.
      Parameters:
      name - the backdrop's name
      imagePath - the image file

    • addBackdrop

      public void addBackdrop(String imagePath)
      Adds a backdrop, named after its file.
      Parameters:
      imagePath - the image file, or a built-in sprite's name

    • addBackdrop

      public void addBackdrop(String name, String imagePath, boolean stretch)
      Adds a backdrop, optionally stretched to the stage's size.
      Parameters:
      name - the backdrop's name
      imagePath - the image file, or a built-in sprite's name
      stretch - whether to stretch it to the stage's size

    • setCursor

      public void setCursor(String path)
      Shows an image instead of the mouse pointer while the mouse is over the stage.
      Parameters:
      path - an image file, or a built-in sprite's name

    • setCursor

      public void setCursor(String path, int x, int y)
      Shows an image instead of the mouse pointer.
      Parameters:
      path - an image file, or a built-in sprite's name
      x - pixels from the image's left edge to the point that clicks
      y - pixels from the image's top edge to the point that clicks

    • switchBackdrop

      public void switchBackdrop(String name)
      Switches to the backdrop with that name and tells the stage and every sprite (whenBackdropSwitches); an unknown name changes nothing.
      Parameters:
      name - the backdrop's name
      Scratch Block:
      switch backdrop to [name v]

    • nextBackdrop

      public void nextBackdrop()
      Switches to the next backdrop, after the last to the first.
      Scratch Block:
      next backdrop

    • previousBackdrop

      public void previousBackdrop()
      Switches to the previous backdrop, before the first to the last.
      Scratch Block:
      switch backdrop to [previous backdrop v]

    • randomBackdrop

      public void randomBackdrop()
      Switches to a random backdrop other than the current one (if there is another).
      Scratch Block:
      switch backdrop to [random backdrop v]

    • getCurrentBackdropName

      public String getCurrentBackdropName()
      Returns:
      the current backdrop's name, or null without backdrops
      Scratch Block:
      (backdrop [name v])

    • getCurrentBackdropIndex

      public int getCurrentBackdropIndex()
      Returns:
      the current backdrop's number, counting from 0
      Scratch Block:
      (backdrop [number v])

    • whenBackdropSwitches

      public void whenBackdropSwitches(String name)
      Called when the backdrop switches.
      Parameters:
      name - the new backdrop's name

    • setColorEffect

      public void setColorEffect(double value)
      Scratch's colour effect on the backdrop: shifts its colours around the colour wheel (200 is all the way round). Like Scratch, it gives colours too grey or too dark to show a hue a little one, so white and black are tinted too.
      Parameters:
      value - the effect
      Scratch Block:
      set [color v] effect to (value)

    • changeColorEffect

      public void changeColorEffect(double by)
      Parameters:
      by - how much to change the backdrop's colour effect
      Scratch Block:
      change [color v] effect by (by)

    • getColorEffect

      public double getColorEffect()
      Returns:
      the backdrop's colour effect

    • setTransparency

      public void setTransparency(double percent)
      Scratch's ghost effect on the backdrop: the stage colour shows through.
      Parameters:
      percent - 0 opaque, 100 invisible
      Scratch Block:
      set [ghost v] effect to (transparency)

    • changeTransparency

      public void changeTransparency(double by)
      Parameters:
      by - how much to change the backdrop's transparency
      Scratch Block:
      change [ghost v] effect by (step)

    • getTransparency

      public double getTransparency()
      Returns:
      the backdrop's transparency in percent

    • setTint

      public void setTint(Color color)
      Multiplies the backdrop by a colour. Not a Scratch block: Scratch's colour effect is setColorEffect(double).
      Parameters:
      color - the tint, or null for none

    • setColor

      public void setColor(Color color)
      Parameters:
      color - the colour behind the backdrop

    • setColor

      public void setColor(double red, double green, double blue)
      Parameters:
      red - red from 0 to 255
      green - green from 0 to 255
      blue - blue from 0 to 255

    • getColor

      public Color getColor()
      Returns:
      the colour behind the backdrop

    • addSound

      public void addSound(String name, String soundPath)
      Adds a sound (WAV or OGG).
      Parameters:
      name - the sound's name, for playSound(String)
      soundPath - the sound file

    • addSound

      public void addSound(String soundPath)
      Adds a sound, named after its file.
      Parameters:
      soundPath - the sound file

    • playSound

      public void playSound(String name)
      Starts a sound, like Scratch's "start sound"; a sound that is still playing is not started again.
      Parameters:
      name - the sound's name
      Scratch Block:
      start sound [name v]

    • playSoundCopy

      public SoundPlayback playSoundCopy(String name, double volume)
      Starts another copy of a sound, which plays alongside the others: for shots, steps, coins.
      Parameters:
      name - the sound's name
      volume - the copy's volume from 0 to 100
      Returns:
      the copy, to stop it or change its volume

    • stopSound

      public void stopSound(String name)
      Parameters:
      name - the sound to stop

    • stopAllSounds

      public void stopAllSounds()
      Stops every sound this object started.
      Scratch Block:
      stop all sounds

    • isSoundPlaying

      public boolean isSoundPlaying(String name)
      Parameters:
      name - a sound's name
      Returns:
      whether it is playing

    • setVolume

      public void setVolume(double volume)
      Parameters:
      volume - this object's volume from 0 to 100
      Scratch Block:
      set volume to (percent) %

    • changeVolume

      public void changeVolume(double by)
      Parameters:
      by - how much to change the volume
      Scratch Block:
      change volume by (step)

    • getVolume

      public double getVolume()
      Returns:
      this object's volume from 0 to 100
      Scratch Block:
      (volume)

    • eraseAll

      public void eraseAll()
      Erases everything every pen drew and everything stamped, on every layer.
      Scratch Block:
      erase all

    • broadcast

      public void broadcast(String message)
      Sends a message to every sprite and then the stage; their whenIReceive runs at once.
      Parameters:
      message - the message
      Scratch Block:
      broadcast [message v]

    • whenIReceive

      public void whenIReceive(String message)
      Called when a message is broadcast.
      Parameters:
      message - the message
      Scratch Block:
      when I receive [message v]

    • whenKeyPressed

      public void whenKeyPressed(KeyCode key)
      Called when a key is pressed, once per press.
      Parameters:
      key - the key
      Scratch Block:
      when [space v] key pressed

    • whenKeyReleased

      public void whenKeyReleased(KeyCode key)
      Called when a key is released.
      Parameters:
      key - the key

    • whenMouseClicked

      public void whenMouseClicked(MouseCode button)
      Called when a mouse button is pressed anywhere on the stage.
      Parameters:
      button - the button
      Scratch Block:
      when stage clicked

    • whenMouseWheelMoved

      public void whenMouseWheelMoved(double steps)
      Called when the mouse wheel turns.
      Parameters:
      steps - notches; positive is towards the user

    • isKeyPressed

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

    • isMouseDown

      public boolean isMouseDown()
      Returns:
      whether a mouse button is held down
      Scratch Block:
      <mouse down?>

    • getMouse

      public Vector2 getMouse()
      Returns:
      the mouse pointer in world coordinates

    • getMouseX

      public double getMouseX()
      Returns:
      x of the mouse pointer in world coordinates
      Scratch Block:
      (mouse x)

    • getMouseY

      public double getMouseY()
      Returns:
      y of the mouse pointer in world coordinates
      Scratch Block:
      (mouse y)

    • pickRandom

      public int pickRandom(int from, int to)
      A random whole number between two numbers, both included.
      Parameters:
      from - the lowest
      to - the highest
      Returns:
      the number
      Scratch Block:
      (pick random (from) to (to))

    • getTimer

      public Timer getTimer()
      Returns:
      this object's timer, counting game time since it was made or reset
      Scratch Block:
      (timer)

    • waitSeconds

      public void waitSeconds(double seconds)
      Holds up the code that calls it for a number of seconds. Called in main (a program written straight down the page), the game keeps running meanwhile and the seconds are game time. Called in run() or an event, the whole game waits, as it does for any slow code; the window stays responsive.
      Parameters:
      seconds - how long

    • waitUntil

      public void waitUntil(BooleanSupplier condition)
      Holds up the code that calls it until a condition is true; see waitSeconds(double).
      Parameters:
      condition - checked about every millisecond
      Scratch Block:
      wait until <condition>

    • display

      public void display(String text)
      Shows a text in a band along the bottom of the stage until something else is displayed; an empty text removes the band.
      Parameters:
      text - what to show

    • display

      public void display(String text, double seconds)
      Shows a text in a band along the bottom of the stage for a number of seconds of game time.
      Parameters:
      text - what to show
      seconds - how long

    • ask

      public void ask(String question)
      Asks a question in a box along the bottom of the stage, as Scratch does, with a field to type the answer in. Enter or the check button finishes it: then isAsking() is false and getAnswer() has the answer. While a question is open, keys go to the answer box, not to the stage and its sprites.
      Parameters:
      question - the question
      Scratch Block:
      ask [question] and wait

    • isAsking

      public boolean isAsking()
      Returns:
      whether a question is waiting for its answer

    • getAnswer

      public String getAnswer()
      Returns:
      the answer to the last question, "" before the first
      Scratch Block:
      (answer)

    • run

      public void run()
      Runs every tick before the sprites' run(). Override it with the stage's code.