Initial commit

commands/badgeware-api.md

@@ -0,0 +1,176 @@
+---
+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