API REFERENCE

Module jupylet.app

Class App

class jupylet.app.App(width=512, height=512, mode='auto', resource_dir='.', quality=None, **kwargs)

A Jupylet game object.

Parameters

• width (int) – The width of the game canvas in pixels.

• height (int) – The height of the game canvas in pixels.

• mode (str) – Game mode can be ‘jupyter’ for running the game in a Jupyter notebook, ‘window’ for running the game in a Python script, ‘hidden’ for machine learning, or ‘auto’ for let Jupylet choose the appropriate mode automatically.

• resource_dir (path) – A path to the directory of the game assets.

• quality (int) – Quality of game video compression specified as an integer between 10 and 100 for when the Jupyter notebook is run on a remote server.

Methods

App.run(interval=0.03333333333333333)

Start the game.

If the game is run in a Jupyter notebook, the call will return immedately with the canvas object on which the game frames will be redrawn, otherwise the call will block until the game is done.

Parameters

interval (float) – The interval in seconds between frame redraws.

Returns

The ipywidgets object on which the game will be redrawn.

Return type

ipywidgets.widgets.widget_media.Image

App.stop(foo=None)

Stop given handler from running. If no handler is given stop the game.

Parameters

foo (function) – The handler to stop running.

App.set_midi_sound(s)

Start the default MIDI handler with given sound object as its intrument.

Parameters

s (jupylet.audio.sound.Sound) – The sound object to use as MIDI instrument.

App.observe()

Return game canvas content as upside-down-flipped numpy array.

Returns

The content of the game canvas an a Numpy array with the shape H x W x 4 corresponding to an RGBA bitmap image.

Return type

numpy.ndarray

App.scale_window_to(px)

Scale window size so that its biggest dimension (either width or height) is px pixels.

This is useful for RL applications since smaller windows render faster.

Parameters

px (int) – The target size of the rescaled canvas in pixels.

App.save_state(name, path=None, *args)

Save the state of given game objects to disk.

Parameters

• name (str) – If explicit path is not given, name will be used to automatically generate a filename.

• path (str, optional) – An explicit path to use for file.

• *args – A list of object implementing the save_state() method, to save to disk.

Returns

path to saved file.

Return type

str

App.load_state(path, *args)

Load the state of given game objects from disk.

Will also render the scene once all objects are loaded.

Parameters

• path (str, optional) – An explicit path to use for file.

• *args – A list of object implementing the load_state() method, to load from disk.

App.get_logging_widget(height='256px', quiet_default_logger=True)

Returns an output ipywidget to which log messages will be printed.

Returns

an output ipywidget for log messages.

Return type

ipywidgets.widgets.widget_output.Output

App.sonic_live_loop2(times=0, **kwargs)

Schedule an async function to run repeatedly in a loop.

The function is scheduled to run based on its name, so updating its definition in a Jupyter notebook will cause the new definition to replace the previous one.

The new definition will kick in once the current iteration through the loop completes.

Parameters

times (int) – the number of times to run through the loop, or indefinately if 0.

App.sonic_live_loop(times=0, **kwargs)

Schedule an async function to run repeatedly in a loop.

The function is scheduled to run based on its name, so updating its definition in a Jupyter notebook will cause the new definition to replace the previous one.

The new definition will kick in immediately.

Parameters

times (int) – the number of times to run through the loop, or indefinately if 0.

App.run_me_every(interval, **kwargs)

Schedule a function to run after the specified delay.

The function is scheduled to run based on its name, so updating its definition in a Jupyter notebook will cause the new definition to replace the previous one.

Parameters

delay (float) – the schedule delay in seconds.

App.run_me(delay=0, **kwargs)

Schedule a function to run after the specified delay.

The function is scheduled to run based on its name, so updating its definition in a Jupyter notebook will cause the new definition to replace the previous one.

Parameters

delay (float) – the schedule delay in seconds.

App.mouse_position_event(x, y, dx, dy)

Reports the current mouse cursor position in the window

Parameters

• x (int) – X postion of the mouse cursor

• y (int) – Y position of the mouse cursor

• dx (int) – X delta postion

• dy (int) – Y delta position

App.mouse_press_event(x, y, button)

Called when a mouse button in pressed

Parameters

• x (int) – X position the press ocurred

• y (int) – Y position the press ocurred

• button (int) – 1 = Left button, 2 = right button

App.mouse_release_event(x, y, button)

Called when a mouse button in released

Parameters

• x (int) – X position the release ocurred

• y (int) – Y position the release ocurred

• button (int) – 1 = Left button, 2 = right button

App.key_event(key, action, modifiers)

Handle the on_key event.

Parameters

• key (int) – An integer specifying the key.

• action (int) – An integer specifying whether the key was pressed or released.

• modifiers (dict) – A dictionary specifying the state the CTRL, ALT, and SHIFT, keys at the time of the event.

App.render(current_time: float, delta: float)

Handle the on_render event.

Parameters

• current_time (float) – Time in seconds since start of game.

• delta (float) – Time in seconds since previous call to handler.

App.event(*args)

Function decorator for an event handler.

App.close()

Called when the window is closed

App.load_program(path=None, vertex_shader=None, geometry_shader=None, fragment_shader=None, tess_control_shader=None, tess_evaluation_shader=None, defines: Optional[dict] = None, varyings: Optional[List[str]] = None) → Program

Loads a shader program.

Note that path should only be used if all shaders are defined in the same glsl file separated by defines.

If the path is relative the resource system is used expecting one or more resource directories to be registered first. Absolute paths will attempt to load the file directly.

Keyword Arguments

• path (str) – Path to a single glsl file

• vertex_shader (str) – Path to vertex shader

• geometry_shader (str) – Path to geometry shader

• fragment_shader (str) – Path to fragment shader

• tess_control_shader (str) – Path to tessellation control shader

• tess_evaluation_shader (str) – Path to tessellation eval shader

• defines (dict) – #define values to replace in the shader source. Example: {'VALUE1': 10, 'VALUE2': '3.1415'}.

• varyings (List[str]) – Out attribute names for transform shaders

Returns

The program instance

Return type

moderngl.Program

Properties

App.width

Width of game canvas in pixels.

Type

bool

App.height

Height of game canvas in pixels.

Type

bool

Module jupylet.sprite

Class Sprite

class jupylet.sprite.Sprite(img, x=0, y=0, scale=1.0, angle=0.0, anchor_x='center', anchor_y='center', color='white', flip=True, mipmap=True, autocrop=False, anisotropy=8.0, height=None, width=None, name=None, collisions=True)

A 2D game sprite.

Parameters

• img – either a path to a sprite image, a PIL Image object, or a numpy array with image pixel data.

• x (float) – The x position for the sprite.

• y (float) – The y position for the sprite.

• scale (float) – value by which to scale the sprite up or down.

• angle (float) – clockwise rotation of the sprite in degrees.

• anchor_x (float or str) – either ‘left’, ‘center’ or ‘right’ or a value between 0.0 (for left) and 1.0 (for right) indicating the anchor point inside the sprite along its x axis.

• anchor_y (float or str) – either ‘bottom’, ‘center’ or ‘top’ or a value between 0.0 (for bottom) and 1.0 (for top) indicating the anchor point inside the sprite along its y axis.

• color (str or 3-tuple) – color by which to tint sprite image. Could be a color name, color hex notation, or a 3-tuple.

• flip (bool) – flip the sprite upside down or not.

Methods

Sprite.render(shader=None)

Render sprite to canvas.

Parameters

shader (moderngl.program.Program, optional) – OpenGL shader program to use for rendering.

Sprite.draw(shader=None)

Render sprite to canvas - this is an alias to Sprite.render().

Sprite.set_anchor(ax=None, ay=None)

Set the anchor point of the sprite.

The anchor is a point in the sprite that is used for rotation and positioning. Imagine a pin going through the sprite and that you use this pin to position the sprite on the canvas and to rotate it. The point at which the pin goes through the texture is the anchor point.

The anchor point is set separately for the x axis, and for the y axis.

Parameters

• ax (str or float) – the x anchor can be one of ‘left’, ‘center’, ‘right’, or a float value between 0.0 (left) and 1.0 (right).

• ay (str or float) – the y anchor can be one of ‘bottom’, ‘center’, ‘top’, or a float value between 0.0 (bottom) and 1.0 (top).

Sprite.collisions_with(o, debug=False)

Compute collisions with given sprite.

Parameters

o (Sprite) – The other sprite with which to check collisions.

Returns

An 2d array with collision points or an empty array if sprites do not collide.

Return type

numpy.ndarray

Sprite.distance_to(o=None, pos=None)

Compute the distance to another sprite or coordinate.

Parameters

• o (Sprite, optional) – Other sprite to compute distance to.

• pos (tuple, optional) – An (x, y) coordinate to compute distance to.

Returns

Distance in pixels.

Return type

float

Sprite.angle_to(o=None, pos=None)

Compute clockwise angle in degrees to another sprite or coordinate.

Parameters

• o (Sprite, optional) – Other sprite to compute angle to.

• pos (tuple, optional) – An (x, y) coordinate to compute angle to.

Returns

Angle in degrees.

Return type

float

Sprite.wrap_position(width, height, margin=50)

Wrap sprite’s coordinates around given canvas width and height.

Use this method to make the sprite come back from one side of the canvas if it goes out from the opposite side.

Parameters

• width (float) – The canvas width to wrap around.

• height (float) – The canvas height to wrap around.

• margin (float, optional) – An extra margin to add around canvas before wrapping the sprite around to the opposite side.

Sprite.clip_position(width, height, margin=0)

Clip sprite’s coordinates to given canvas width and height.

Use this method to prevent the sprite from going out of the canvas.

Parameters

• width (float) – The canvas width to clip to.

• height (float) – The canvas height to clip to.

• margin (float, optional) – An extra margin to add around canvas before clipping the sprite’s coordinates.

Sprite.get_state()

Get a dictionary of properties defining the object state.

Returns

A dictionary of properties.

Return type

dict

Sprite.set_state(s)

Set object state from given dictionary of properties.

Parameters

s (dict) – A dictionary of properties previously returned by a call to get_state().

Properties

Sprite.scale

Scale of sprite.

The scale equals the rendered width in pixels divided by the actual width of the texture. E.g a scale of 2 will make the sprite appear twice as big than it originally is, and a scale of 1/2 twice as small.

Type

float

Sprite.x

The x coordinate of the anchor position.

Type

float

Sprite.y

The y coordinate of anchor position.

Type

float

Sprite.angle

The rotation angle around the anchor in degrees.

Type

float

Sprite.width

Width in pixels after scaling.

Type

float

Sprite.height

Height in pixels after scaling.

Type

float

Sprite.image

Bitmap image of sprite.

You can set this property with a new image or with a path to an image on disk to change the current sprite image.

Type

PIL.Image.Image

Sprite.top

Get the top coordinate of the sprite’s bounding box.

Type

float

Sprite.right

Get the right coordinate of the sprite’s bounding box.

Type

float

Sprite.bottom

Get the bottom coordinate of the sprite’s bounding box.

Type

float

Sprite.left

Get the left coordinate of the sprite’s bounding box.

Type

float

Sprite.radius

Get the radius of a circle containing the sprite’s bounding box.

Type

float

Sprite.opacity

Get or set the opacity of the sprite.

Setting opacity to 0 would render the sprite completely transparent. Settint opacity to 1 would render the sprite completely opaque.

Type

float

Sprite.color

Get or set the color of the sprite.

The sprite color will be multiplied by the color values of its bitmap image.

The color can be specified by name (e.g. ‘white’) or in hex notation (e.g ‘#cc4488’) or as a 4-tuple or glm.vec4 value.

Type

glm.vec4

Sprite.flip=True

Flip the image upside down while rendering.

Type

bool

Sprite.mipmap=True

Compute mipmap textures when first loading the sprite image.

Type

bool

Sprite.autocrop=False

Auto crop the image to its bounding box when first loading the sprite image.

Type

bool

Sprite.anisotropy=8.0

Use anisotropic filtering when rendering the sprite image.

Type

float

Module jupylet.label

Class Label

class jupylet.label.Label(text='', font_path='fonts/SourceSerifPro-Bold.otf', font_size=16, line_height=1.2, align='left', bold=False, italic=False, color='white', x=0, y=0, angle=0.0, width=None, height=None, anchor_x='left', anchor_y='baseline')

A text label.

Since a text label is actually implemented as a 2D sprite, it has all the functionality and methods of a Sprite.

Parameters

• text (str) – text to render as label.

• font (path) – path to a true type or open type font.

• font_size (float) – font size to use.

• line_height (float) – determines the distance between lines.

• align (str) – the desired alignment for the text label. May be one of ‘left’, ‘center’, and ‘right’.

• color (str or 3-tuple) – a color name, color hex notation, or a 3-tuple. specifying the color for the text label.

• x (float) – the x position for the label.

• y (float) – the y position for the label.

• angle (float) – clockwise rotation of the label in degrees.

• anchor_x (float or str) – either ‘left’, ‘center’ or ‘right’ or a value between 0.0 (for left) and 1.0 (for right) indicating the anchor point inside the label along its x axis.

• anchor_y (float or str) – either ‘bottom’, ‘baseline’, ‘center’ or ‘top’ or a value between 0.0 (for bottom) and 1.0 (for top) indicating the anchor point inside the label along its y axis.

Properties

Label.text

Text to render as label.

Type

str

Label.font_path

Path to a true type or open type font.

Type

str

Label.font_size=16

Font size to use.

Type

float

Label.line_height=1.2

Determines the distance between lines.

Type

float

Label.align='left'

The desired alignment for the text label. May be one of ‘left’, ‘center’, and ‘right’.

Type

str

Module jupylet.loader

jupylet.loader.load_blender_gltf(path)

Load a Blender scene or model exported with the Blender glTF 2.0 exporter.

The Blender scene should be exported using the glTF Separate (.gltf + .bin + textures) format. In the exporter make sure to check the Apply Modifiers, UVs, and Normals, options checkboxes.

Note that in principle this function should be able to load any gltf 2.0 scene, however it was only tested with and tuned to load scenes exported with Blender 2.83 and Blender 3.4.

Parameters

path (str) – path to glTF 2.0 file.

Returns

A scene object.

Return type

Scene

Module jupylet.model

Class Scene

class jupylet.model.Scene(name, shadows=False)

A 3D Scene object.

While it is possible to create a Scene object manually, it is probably a better idea to call jupylet.loader.load_blender_gltf() instead.

Methods

Scene.draw(shader=None)

Render scene to canvas.

Parameters

shader (moderngl.program.Program, optional) – OpenGL shader program to use for rendering.

Properties

Scene.meshes

A list of meshes.

Type

list

Scene.lights

A list of lights.

Type

list

Scene.cameras

A list of cameras.

Type

list

Scene.materials

A list of materials.

Type

list

Scene.skybox

A Skybox object.

Type

Skybox

Scene.shadows

Set to True to enable shadows.

Type

bool

Scene.name

Name of scene.

Type

str

Class Mesh

class jupylet.model.Mesh(name, rotation=None, scale=None, position=None, parent=None)

A 3D Mesh object.

While it is possible to create a Mesh object manually, it is probably a better idea to call jupylet.loader.load_blender_gltf() instead.

Methods

Mesh.move_local(xyz)

Move by given displacement in local coordinate system.

Parameters

xyz (glm.vec3) – Displacement.

Mesh.move_global(xyz)

Move by given displacement in global coordinate system.

Parameters

xyz (glm.vec3) – Displacement.

Mesh.rotate_local(angle, axis=(0.0, 0.0, 1.0))

Rotate counter clockwise by given angle around given axis in local coordinate system.

Parameters

• angle (float) – Angle in radians.

• axis (glm.vec3) – Rotation axis.

Mesh.rotate_global(angle, axis=(0.0, 0.0, 1.0))

Rotate counter clockwise by given angle around given axis in global coordinate system.

Parameters

• angle (float) – Angle in radians.

• axis (glm.vec3) – Rotation axis.

Properties

Mesh.front

Return the local front (+z) axis.

Type

glm.vec3

Mesh.up

Return the local up (+y) axis.

Type

glm.vec3

Mesh.primitives

List of primitives the mesh consists of.

Type

list

Mesh.children

List of child meshes.

Type

list

Mesh.hide

Set to False to hide mesh from view.

Type

bool

Mesh.name

Name of mesh.

Type

str

Module jupylet.audio

jupylet.audio.sonic_py(resource_dir='.')

Start an audio application.

An audio application is need to run live loops.

Parameters

resource_dir (str) – Path to root of resource dir, for samples, etc…

Returns

A running application object.

Return type

App

jupylet.audio.set_bpm(bpm=240)

Set the tempo to the given beats per minute.

Parameters

bpm (float) – Beats per minute.

jupylet.audio.set_note_value(v=4)

Set the note value representing one beat.

Parameters

v (float) – Note value.

jupylet.audio.use(sound, **kwargs)

Set the instrument to use in subsequent calls to play().

You can supply key/value pairs of properties to modify in the given instrument. If you do, the instrument will be copied first, and the modifications will be applied to the new copy.

Parameters

• sound (GatedSound) – Instrument to use.

• **kwargs – Properties of intrument to modify.

jupylet.audio.play(note, duration=None, **kwargs)

Play given note polyphonically with the instrument previously set by call to use().

You can supply key/value pairs of properties to modify in the given instrument.

Parameters

• note (float) – Note to play in units of semitones where 60 is middle C.

• duration (float, optional) – Duration to play note, in whole notes.

• **kwargs – Properties of intrument to modify.

jupylet.audio.sleep(duration=0)

Get some sleep.

Example

@app.sonic_live_loop2
async def boom_pam():

    use(tb303, resonance=8, decay=1/8, cutoff=48, amp=1)

    play(C2, 1/8)
    await sleep(1/4)

    play(C3, 1/8)
    await sleep(1/4)

Parameters

duration (float) – Duration to sleep in whole notes.

Returns

A sleep coroutine to use with await.

Return type

coroutine

Module jupylet.audio.sound

Class Sound

Methods

Properties

Sound.freq

Fundamental requency of sound object.

Type

float

Sound.amp

Output amplitude - a value between 0 and 1.

Type

float

Sound.pan

Balance between left (-1) and right (1) output channels.

Type

float

Class Oscillator

Methods

Properties

Oscillator.shape

Waveform to generate - one of sine, triangle, sawtooth, or square.

Type

str

Oscillator.sign

Set to -1 to flip sawtooth waveform upside down.

Type

float

Oscillator.duty

The fraction of the square waveform cycle its value is 1.

Type

float

Class LatencyGate

Methods

Class GatedSound

Methods

Module jupylet.audio.sample

Class Sample

Methods

Properties

Sample.path

Path to audio file.

Type

str