---
description: Quick reference for the badgeware API with code examples
---

# 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
```python
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
```python
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
```python
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
```python
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
```python
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
```python
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
```python
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
```python
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
```python
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:
- https://github.com/badger/home/blob/main/badgerware/Image.md
- https://github.com/badger/home/blob/main/badgerware/shapes.md
- https://github.com/badger/home/blob/main/badgerware/brushes.md
- https://github.com/badger/home/blob/main/PixelFont.md
- https://github.com/badger/home/blob/main/Matrix.md
- https://github.com/badger/home/blob/main/badgerware/io.md