Strype API documentation¶
You can see more documentation for Strype on the main documentation page <https://strype.org/doc/>
strype.graphics module¶
- class strype.graphics.Actor(image, x=0, y=0, tag=None)¶
Bases:
objectAn Actor is an item in the world with a specific image, position, rotation and scale. If an actor is created, it becomes visible in the graphics world.
Create a new Actor. An actor has an image and a location. It can optionally have a tag. A tag (usually a string) can be used to group actors and identify them later for collision detection.
The image parameter must be an
Imageobject.The (x, y) coordinate determines the location of the actor. The graphics world coordinate system has x coordinates from -400 to 400, and y coordinates from -300 to 300. The origin (0, 0) point is in the center; (-400, -300) is the bottom left.
- Parameters:
- get_all_touching(tag=None)¶
Return all the actors that this actor is touching.
If the tag is specified, only actors with the given tag will be included.
- get_exact_x()¶
Return the exact x coordinate of the actor, which may be a fractional number. For simpler coordinate calculations using whole numbers, call get_x() instead.
- Returns:
The exact x coordinate, or None if the actor has been removed from the world.
- Return type:
- get_exact_y()¶
Return the exact y coordinate of the actor, which may be a fractional number. For simpler coordinate calculations using whole numbers, call get_y() instead.
- Returns:
The exact y coordinate, or None if the actor has been removed from the world.
- Return type:
- get_image()¶
Return the image of this actor. The image object returned is the actual actor’s live image – drawing on it will become visible on the actor’s image.
- get_in_range(distance, tag=None)¶
Return all actors which are within a given distance of this actor. The distance is measured as the distance of the logical location (the center point) of each actor.
If a tag is specified, only actors with the given tag will be returned.
- get_rotation()¶
Return the current rotation of this actor.
- Returns:
The rotation of this Actor, in degrees, or None if the actor has been removed from the world.
- Return type:
- get_tag()¶
Return the tag of this actor.
- Returns:
The tag, as set during the creation of this actor.
- Return type:
Any | None
- get_touching(tag=None)¶
Return an actor touching this one.
If more than one actor is touching this one, a random one of these actors will be returned. If a tag is passed as a parameter, only actors with that tag will be considered.
Two actors are deemed to be touching if the bounding rectangles of their images are overlapping (even if the actor is transparent at that point).
- get_x()¶
Return the x coordinate of the actor as an integer (whole number). If the actor’s exact position is not a whole number, it is rounded down (towards zero). To receive the exact position as a potentially fractional number, call get_exact_x().
- Returns:
The current x coordinate, as an integer, or None if the actor has been removed from the world.
- Return type:
- get_y()¶
Return the y coordinate of the actor as an integer (whole number). If the actor’s exact position is not a whole number, it is rounded down (towards zero). To receive the exact position as a potentially fractional number, call get_exact_y().
- Returns:
The current y coordinate, as an integer, or None if the actor has been removed from the world.
- Return type:
- is_at_edge(distance=2)¶
Check whether the actor is at the edge of the world. An actor is considered to be at the edge if its location (its center point) is within distance pixels of the world bounds.
- is_touching(actor_or_tag)¶
Check if this actor is touching the another actor.
Two actors are deemed to be touching if the bounding rectangles of their images are overlapping (even if the actor is transparent at that point).
The parameter can be either a specific actor (of type
Actor) or a tag. If a tag is used, this function will return True if any actor with this tag is touched.
- move(distance)¶
Move forward the given distance in the current direction. The direction of travel can be changed using set_rotation() or turn().
Actors are stopped at the edge of the world – they cannot move outside of the world.
- Parameters:
distance (float) – The distance to move (in pixels). Negative amounts move backwards.
- Return type:
None
- remove()¶
Remove the actor from the world. Once an actor has been removed, it cannot be re-added to the world.
- Return type:
None
- remove_touching(tag=None)¶
Remove a touching actor.
If this actor is not currently touching another actor, do nothing. If this actor currently touches more than one actor, one random actor currently toouching is removed. If a tag is specified, only actors with the given tag will be removed.
- Parameters:
tag (Any | None) – The tag to use to filter the actors (or None to consider all actors)
- Return type:
None
- say(text, font_size=24, max_width=300, max_height=200, font_family=None)¶
Show a speech bubble next to the actor with the given text. The only required parameter is the text, all others are optional. n can be used to start a new line.
If a maximum width is specified, the text will be wrapped to fit the given width. If a maximum height is specified as well, the font size will be reduced if necessary to fit within the width and height. If the text is too long, it may exceed the maximum width or height.
To remove the speech bubble, call say(“”) (that is, with an empty string). See also say_for to display text for a fixed time.
- say_for(text, seconds, font_size=24, max_width=300, max_height=200)¶
say_for acts like the say function, but automatically removes the speech bubble after the given number of seconds. For all other parameters, see the say function for an explanation.
- Parameters:
- Return type:
None
- set_image(image)¶
Set an actor’s image
The image parameter must be an
Imageobject. :param image: AnImageobject.- Parameters:
image (Image)
- Return type:
None
- set_location(x, y)¶
Set the location of the actor.
If the location is outside the bounds of the world, it will be adjusted to the nearest point inside the world.
- set_rotation(degrees)¶
Set the rotation of the actor. This changes the rotation of the actor’s image, and it also affects the direction of movement when move() is called.
- Parameters:
degrees (float) – The rotation in degrees (0 points right, 90 points up, 180 points left, 270 points down).
- Return type:
None
- class strype.graphics.Color(red, green, blue, alpha=255)¶
Bases:
objectA Color class with red, green, blue components, and an optional alpha value.
Create a color object with red, green, blue and alpha (transparency) values. Parameters are in the range 0–255. Parameters below 0 they will be treated as 0; parameters above 255 will be treated as 255.
- class strype.graphics.Image(width, height)¶
Bases:
objectAn editable image of fixed width and height.
Create an editable image with the given dimensions. The initial image is empty (fully transparent). For reference: the size of the Strype graphics world is 800x600 pixels.
- Parameters:
- clear()¶
Clears the image (i.e. sets all the pixels to be fully transparent).
- Return type:
None
- clone(scale=1.0)¶
Return a copy of this image.
- download(filename='strype-image')¶
Triggers a download of this image as a PNG image file. You can optionally pass a file name (you do not need to include the file extension, Strype will add that automatically). To help you distinguish downloads from repeated runs, Strype will automatically add a timestamp to the file.
To avoid problems with accidentally calling this method too often, Strype will limit the rate of downloads to at most one every 2 seconds.
- Parameters:
filename (str) – The main part of the filename to use for the downloaded file.
- Return type:
None
- draw_circle(centre_x, centre_y, radius)¶
Draw a circle at a given position. The border is drawn using the stroke color (see set_stroke) and filled using the current fill color (see set_fill).
- draw_image(image, x, y)¶
Draw another image onto this image.
- draw_line(start_x, start_y, end_x, end_y)¶
Draw a line. The line is drawn in the current stroke color.
- draw_oval(centre_x, centre_y, x_radius, y_radius, angle_start=0, angle_amount=360)¶
Draws an oval or part of one (also known as an ellipse; a circle with a width that can be different than height).
If you want to draw part of an oval, pass the last two parameters. Imagine an oval with a given centre position and X/Y radius. The angle_start parameter is the angle from the centre to the start of the arc, in degrees (0 points to the right, positive values go clockwise), and the angle_amount is the amount of degrees to travel (positive goes clockwise, negative goes anti-clockwise) to the end point.
The oval will be filled with the current fill (see set_fill()) and drawn in the current stroke (see set_stroke()).
- Parameters:
centre_x (float) – The centre x coordinate of the oval.
centre_y (float) – The centre y coordinate of the oval.
x_radius (float) – The radius of the oval on the X axis.
y_radius (float) – The radius of the oval on the Y axis.
angle_start (float) – The starting angle of the arc, in degrees (0 points to the right).
angle_amount (float) – The amount of degrees to travel (positive goes clockwise).
- Return type:
None
- draw_polygon(points)¶
Draw a polygon with the given corner points. The last point will be connected to the first point to close the polygon.
The border is drawn using the stroke color (see set_stroke) and filled using the current fill color (see set_fill). The polygon should be convex, otherwise the visual behaviour is undefined.
- draw_rect(x, y, width, height)¶
Draw a rectangle. The border is drawn using the stroke color (see set_stroke) and filled using the current fill color (see set_fill).
- draw_rounded_rect(x, y, width, height, corner_size=10)¶
Draw a rectangle with rounded corners. The border is drawn using the stroke color (see set_stroke) and filled using the current fill color (see set_fill).
- Parameters:
x (float) – The x coordinate of the top-left of the rectangle.
y (float) – The y coordinate of the top-left of the rectangle.
width (float) – The width of the rectangle.
height (float) – The height of the rectangle.
corner_size (float) – The radius of the rounded corners of the rectangle. Defaults to 10 if omitted.
- Return type:
None
- draw_text(text, x, y, font_size=32, max_width=0, max_height=0, font_family=None)¶
Draw text onto the image. If a maximum width is specified, the text will be wrapped to fit the given width. If a maximum height is specified as well, the font size will be reduced if necessary to fit within the width and height. If the text is too long, it may exceed the maximum width or height.
The text color is the current fill color (see set_fill()).
- Parameters:
text (str) – The text to draw.
x (float) – The x coordinate of the top-left corner of the text.
y (float) – The y coordinate of the top-left corner of the text.
font_size (float) – The size of the text, in pixels.
max_width (float) – The maximum width of the text (or 0 for no maximum).
max_height (float) – The maximum height of the text (or 0 for no maximum).
font_family (str | None)
- Returns:
A named tuple width width and height of the actually drawn area.
- Return type:
Dimension
- fill()¶
Fill the image with the current fill color (see set_fill).
- Return type:
None
- get_height()¶
Return the height of this image.
- Returns:
The height of this image, in pixels.
- Return type:
- get_width()¶
Return the width of this image.
- Returns:
The width of this image, in pixels.
- Return type:
- set_fill(color)¶
Set the current fill color. The fill color is used in subsequent fill and draw operations. Set the fill color to None to draw shape outlines without filling.
- set_pixel(x, y, color)¶
Set the pixel at the given position to a specific color.
- Parameters:
- Return type:
None
- set_stroke(color)¶
Set the current stroke (line) color. This color is used in subsequent draw operations for the shape’s outline. Set the stroke color to None to paint shapes without a separately colored border.
- strype.graphics.color_from_string(html_string)¶
Convert a string to a
Colorobject. The string can be either a color name (e.g. “red”) or a hex string (e.g. “#ff0000”). A hex string can either be 6 hex digits (in which case alpha is assumed to be 255) or 8 hex digits (which includes the alpha).- Parameters:
html_string (str) – A string as described above.
- Raises:
ValueError – If the string is not recognised as a color name or valid 6 or 8 digit hex string.
- Returns:
A
Colorobject.- Return type:
- strype.graphics.get_actors(tag=None)¶
Gets all actors.
If the tag is specified, only actors with the given tag will be included.
- strype.graphics.get_background()¶
Gets the current background image.
Any changes to the image (such as drawing on it) will be shown on the live display.
Note that the image returned by get_background() will not be the same as that passed to set_background(). The image may have been tiled or stretched. It may also not be exactly 800 x 600; the image may be slightly oversized (e.g. 808 x 606) to make sure it covers the edges fully. But its centre will be at (0, 0).
- Returns:
The live background image, or None if one has not been set.
- Return type:
- strype.graphics.get_clicked_actor()¶
Return the last actor receiving a mouse click. If no actor was clicked since this function was last called, None is returned. Every click will be reported only once – a second call to this function in quick succession will return None.
- strype.graphics.get_mouse()¶
Get the details for current mouse state.
- Returns:
A named tuple with details of the mouse state: (x, y, button0, button1, button2) where the last three items are booleans where True indicates the button is held: button0 for primary (left), button1 for secondary (right), button2 for middle.
- Return type:
MouseDetails
- strype.graphics.get_mouse_click()¶
Get the details for the last mouse click. If the mouse was not clicked since this function was last called, None is returned. Every click will be reported only once – a second call to this function in quick succession will return None.
This function is independent of get_clicked_actor(); they will potentially report details of the same mouse click it was on an actor.
- Returns:
A named tuple with details of the last click: (x, y, button, click_count) where button is 0 for primary (left), 1 for secondary (right) or 2 for middle; or None if the mouse was not clicked since the last call.
- Return type:
ClickDetails | None
- strype.graphics.key_pressed(keyname)¶
Check if a given key is currently pressed down.
The names of printable keys are the character they print (e.g. “a” for the a-key). Other keys have names describing their function. These include “left”, “right”, “up, “down”, “enter”, “tab”, “escape”, “shift”, “control”, “alt”, “backspace”, delete”.
- strype.graphics.load_image(name)¶
Load the given image and return it as an
Imageobject. The image name must be the name of one of the images in the Strype image library.
- strype.graphics.pace(actions_per_second=25)¶
Wait for a suitable amount of time since the last call to pace(). This is almost always used as follows:
while True: # Do all the actions you want to do in one iteration pace(25)
Where 25 is the number of times you want to do those actions per second. It is like sleeping for 1/25th of a second, but it accounts for the fact that your actions may have taken some time, so it aims to keep you executing the actions 25 times per second (or whatever value you pass for actions_per_second).
- Parameters:
actions_per_second (float) – The amount of times you want to call pace() per second, 25 by default.
- Return type:
None
- strype.graphics.pause(seconds)¶
Pause for the given amount of seconds.
This can be a fractional amount, such as 0.5, or 1.2. The entire code will pause for that length of time before beginning to execute.
- Parameters:
seconds (float) – The amount of seconds to wait for.
- Return type:
None
- strype.graphics.set_background(image_or_color, scale_to_fit=False)¶
Set the current background image.
The parameter can be an
Image, aColor, or a color name or hex string.If scale_to_fit is True, the image will be scaled (up or down) so that it fills the world area (800x600 pixels). Otherwise the image will be drawn in the center of the world in its original size, and tiled outwards if it is smaller than the world.
The background image is always copied when it is created, so later changes to the original image will not be shown in the world. You can call get_background() to receive the actual background image object to change it.
- strype.graphics.stop()¶
Stop the execution of the program. This function will not return.
- Return type:
None
strype.sound module¶
- class strype.sound.Sound(seconds, samples_per_second=44100)¶
Bases:
objectCreates a new silent/empty sound object. The first parameter indicates a length in seconds, and the optional second parameter indicates the sample rate (samples per second).
- Parameters:
- clone()¶
Returns a copy of this sound.
- Returns:
A copy of this sound (leaving this sound unmodified).
- Return type:
- copy_to_mono()¶
Returns a copy of this sound which is mono (i.e. one channel, rather than left/right).
If you want to work with the sound via get_samples() and set_samples(), you can only do this on a mono sound.
- Returns:
A copy of this sound (leaving this sound unmodified) with the content of this one converted to mono.
- Return type:
- download(filename='strype-sound')¶
Triggers a download of this sound as a WAV sound file. You can optionally pass a file name (you do not need to include the file extension, Strype will add that automatically). To help you distinguish downloads from repeated runs, Strype will automatically add a timestamp to the file.
To avoid problems with accidentally calling this method too often, Strype will limit the rate of downloads to at most one every 2 seconds.
- Parameters:
filename (str) – The main part of the filename to use for the downloaded file.
- Return type:
None
- get_num_samples()¶
Gets the length of the sound, in samples.
- Returns:
The length of the sound, in number of samples.
- Return type:
- get_sample_rate()¶
Gets the number of samples per second in the sound. This can be different for different sound files.
- Returns:
The number of samples per second in the sound.
- Return type:
- get_samples()¶
Gets all the samples from the sound. This will be a list of numbers, each in the range -1 to +1.
- play()¶
Starts playing the sound from the start, but returns immediately without waiting for the sound to finish playing.
- Return type:
None
- play_and_wait()¶
Plays the sound. Does not return until the sound has finished playing.
- Return type:
None
- set_samples(sample_list, copy_to_sample_index)¶
Copies the given list of sample values (which should each be in the range -1 to +1, with 0 as the middle) to the given point in the destination sound. It is okay if the list does not reach to the end of the sound, but you will get an error if the list reaches beyond the end of the sound.
- stop()¶
Stops the sound that was previously played with play(), if it is still playing.
- Return type:
None
- strype.sound.load_sound(source)¶
Loads the given sound file as a Sound object.
Note that most browsers will resample loaded sounded files to a fixed rate (44100 or 48000). So the sample rate of a loaded sound file will probably not match the original file you are loading from. You can call get_sample_rate() on the loaded sound to get the actual sample rate.
- Note: you can pass a filename for the sound, which is a sound name from Strype’s sound library,
or a URL to an image. Using a URL requires the server to allow remote loading from Javascript via a feature called CORS. Many servers do not allow this, so you may get an error even if the URL is valid and you can load the sound in a browser yourself.