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
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
- 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