Badgeware API Reference

Provide a quick reference for the badgeware module API based on the user's search term or show overview if no term provided.

Display & Graphics

Screen Drawing

from badgeware import screen, brushes, shapes

# Set brush color (RGB 0-255)
screen.brush = brushes.color(r, g, b)
screen.brush = brushes.color(r, g, b, alpha)  # With transparency

# Clear screen
screen.clear()

# Draw text
screen.text("Hello", x, y)

# Load and use custom fonts
screen.font = PixelFont.load("/system/assets/fonts/ark.ppf")

Shapes

from badgeware import shapes

# Draw shapes
screen.draw(shapes.rectangle(x, y, width, height))
screen.draw(shapes.circle(x, y, radius))
screen.draw(shapes.line(x1, y1, x2, y2))
screen.draw(shapes.rounded_rectangle(x, y, w, h, radius))

Images & Sprites

from badgeware import Image

# Load and display images
img = Image.load("sprite.png")
screen.blit(img, x, y)
screen.scale_blit(img, x, y, width, height)

# Enable antialiasing for smooth edges
screen.antialias = Image.X4

Button Handling

Button Constants

from badgeware import io

# Available buttons
io.BUTTON_A
io.BUTTON_B
io.BUTTON_C
io.BUTTON_UP
io.BUTTON_DOWN
io.BUTTON_HOME  # Exits to MonaOS menu

Button States

def update():
    # Just pressed this frame
    if io.BUTTON_A in io.pressed:
        print("A pressed")

    # Just released this frame
    if io.BUTTON_B in io.released:
        print("B released")

    # Currently held down
    if io.BUTTON_C in io.held:
        print("C is held")

    # State changed this frame
    if io.BUTTON_UP in io.changed:
        print("UP state changed")

Animation & Timing

Frame Counter

from badgeware import io
import math

frame = 0

def update():
    global frame

    # Use frame counter for animations
    radius = 10 + int(math.sin(frame / 20) * 5)

    # Breathing animation (4-second cycle at 30fps)
    phase = ((frame % 120) / 120.0) * 2 * math.pi
    scale = 20 + int(math.sin(phase) * 15)

    frame += 1

Timing

import time

# Track elapsed time
start_time = time.time()
elapsed = time.time() - start_time

# Sleep (use sparingly, blocks update loop)
time.sleep(0.1)

Transformations

Matrix Transforms

from badgeware import Matrix

# Create and apply transformations
rect = shapes.rectangle(-1, -1, 2, 2)
rect.transform = Matrix() \
    .translate(80, 60) \
    .scale(20, 20) \
    .rotate(io.ticks / 100)  # Animated rotation

screen.draw(rect)

Persistent Storage

File Operations

import json

# Write app data (writable partition)
with open("/storage/myapp_data.json", "w") as f:
    json.dump({"score": 100}, f)

# Read app data
with open("/storage/myapp_data.json", "r") as f:
    data = json.load(f)

Display Specifications

Resolution: 160x120 framebuffer (pixel-doubled to 320x240 physical display)
Colors: Full RGB (0-255 per channel)
Fonts: 30 licensed pixel fonts in /system/assets/fonts/
Automatic Updates: Display refreshes after each update() call

Important Notes

⚠️ This badge uses badgeware module, NOT badger2040! The APIs are different.

⚠️ Frame Rate: MonaOS calls update() ~30 times per second. Keep operations fast.

⚠️ Screen Coordinates: Origin (0,0) is top-left corner.

Full Documentation

For complete API documentation, see:

/badgeware-api