The stage¶

Your project must have a class for the stage, which must be derived from the pytch.Stage class. For example,

class Stage(pytch.Stage):
    # Code for your stage goes here

Methods and properties available on the Stage¶

Your own version of the Stage can use the following methods, which are provided by Pytch:

self.start_sound(sound_name_or_index)
self.play_sound_until_done(sound_name_or_index): These methods work in the same way as the ones provided by the Sprite class. See the help in the Sprite page for details. The given sound_name_or_index must refer to a Sound you have defined — see Defining sounds.

self.stop_all_sounds(): Immediately stop all sounds from playing, including those being played by any Sprites.

self.switch_backdrop(backdrop_name)¶: Make the Stage change its backdrop to the one with the given backdrop_name. This must be the label of a Backdrop defined by the class’s Backdrops variable — see Defining backdrops.

self.switch_backdrop(backdrop_number): Make the Stage change its backdrop to the one at the given position in its list of Backdrops. Zero-based indexing is used, which means that to switch to the first backdrop, use self.switch_backdrop(0); to switch to the second backdrop, use self.switch_backdrop(1); and so on.

self.next_backdrop()¶: Switch to the next backdrop in the Stage’s list of backdrops. If the Stage is already showing its last backdrop, switch to showing the first one.

self.next_backdrop(n_steps): Switch to the backdrop n_steps later in the Stage’s list of backdrops. If this takes you beyond the end of the list, wrap back round to the start as if in a circle. You can use a negative number as n_steps to move to an earlier backdrop; for example, self.next_backdrop(-1) will change to the previous backdrop.

self.backdrop_number¶: The zero-based number of the currently-shown backdrop. So if the Stage is currently showing its first backdrop, backdrop_number will be 0; if it’s currently showing its second backdrop, backdrop_number will be 1; and so on.

self.backdrop_name¶: The name of the currently-shown backdrop.

Showing and hiding the stage’s variables¶

self.show_variable(variable_name)

In Scratch, you can “show” a variable, either by ticking a box in the UI, or by using the show variable MY-VARIABLE block. Pytch does not have a box to tick, but you can show a sprite’s (or the stage’s) variable with the self.show_variable() function. The argument is the name of the sprite’s (or stage’s) variable, which means you will often want to give a quoted string, for example:

self.show_variable("score")

(There is a more general version available; see its documentation for details.)

self.hide_variable(variable_name): Remove the variable watcher for the variable called variable_name. It is not an error if there is not currently such a watcher. (There is a more general version available; see its documentation for details.)

Sensing¶

self.key_pressed(key_name): Give a True/False answer as to whether the key with name key_name is currently pressed.

Pausing a script¶

self.wait_seconds(n_seconds): Make the script calling wait_seconds() do nothing for n_seconds seconds before resuming. This is done by counting frames, so complicated scripts which render at less than 60fps will wait for the wrong amount of time; fixing this is on the roadmap.

Broadcasting messages¶

self.broadcast(message_string): Broadcast the message message_string, launching any scripts with a matching @pytch.when_I_receive() decorator (hat-block). The script calling broadcast() continues, with the responding scripts running concurrently.

self.broadcast_and_wait(message_string): Broadcast the message message_string, launching any scripts with a matching @pytch.when_I_receive() decorator (hat-block). The script calling broadcast_and_wait() waits until all those responding scripts have finished before continuing.

Stopping all scripts¶

self.stop_all()

Stop all currently-executing scripts. Also stop all sounds, delete all clones, abandon all “ask and wait” questions, and clear all speech bubbles.

stop_all() does the same job as the “red stop” button.

Creating clones of Sprites¶

self.create_clone_of(thing)

Create a new clone of thing. You can create clones in two ways. You can clone the original or an existing clone of one of your Sprites, for example a Sprite clone which is calling the create_clone_of() function:

self.create_clone_of(self)

(Although in this case you can use the simpler self.create_clone().)

Or you can create a clone of a particular class of Sprite:

self.create_clone_of(Spaceship)

In this case, Pytch makes a clone of the original instance of that sprite.

You can also clone any instance of any sprite. For example, if you know there are at least three clones of a Spider sprite, you can create a clone of the third one with:

self.create_clone_of(Spider.all_clones()[2])

You can not clone your Stage.

Asking the user a question¶

Pytch has a method matching Scratch’s ask and wait block. In Scratch, you can find what the user typed using the answer reporter block. In Pytch, the user’s answer is returned to your program from the ask_and_wait() method.

self.ask_and_wait(question)

Pop up an input box asking the question, and wait for the user to type in their answer. Your method is paused while the user is typing their answer, and will continue once the user submits their answer. The answer is returned, so you will usually assign it to a variable. For example, this code assigns the user’s answer to a variable name and then prints out a greeting:

class NightSky(pytch.Stage):
    # [ ... Backdrops, Sounds, other methods, etc. ... ]
    @pytch.when_stage_clicked
    def ask_user_their_name(self):
        name = self.ask_and_wait("What's your name?")
        print(f"Hello, {name}!")

The greeting will appear in the “Output” tab of the Pytch IDE.

Sensing the mouse’s position and button¶

Some devices have a “mouse”, which can be used in your Pytch programs. A mouse can tell where it is, in terms of x and y coordinates. It also has a main button, which is either pressed down or not. Scratch has reporter blocks for these three properties. The stage works the same as your sprites when it comes to finding out about the mouse’s state. See the help in the Sprite page.

(The stage does not have touching_mouse or distance_to_mouse properties, though, as these would not make sense for the stage.)