Prompt file imported from anewcomer/d-bag (.github/prompts/thumby-official-doc.prompt.md). Copyright stays with the author.

Thumby SDK Official Documentation Context

Name: thumby-official-doc
Author: anewcomer

This document provides essential context for AI coding agents developing Thumby games and applications based on the official Thumby SDK documentation.

Thumby Hardware Overview

Display: 72x40 pixel monochrome OLED screen
Controls: 6 buttons (4-way D-pad: Up, Down, Left, Right + 2 action buttons: A, B)
Platform: Tiny keychain-sized gaming device running MicroPython
Screen Dimensions: width = 72, height = 40 pixels
Color: Binary (0 = black/off, 1 = white/on)

Development Environment

Thumby Web Code Editor

URL: https://code.thumby.us/
Features:
- Live emulation for instant testing
- File management (local and device)
- Built-in sprite editor
- Direct USB upload to device (MicroUSB cable required)
- Browser support: Chrome and Edge only
Usage: All code is saved locally in browser storage

API Documentation

Main Docs: https://thumby.us/API/Get-Started/
Language: MicroPython
Import: import thumby

Core Thumby API Reference

API Submodules (v1.7+)

For optimized performance, import only needed submodules:

thumbyGraphics - Graphics and display functions
thumbyHardware - Hardware integration
thumbyButton - Button input handling
thumbyAudio - Sound and audio
thumbyLink - Multiplayer link functionality
thumbySaves - Save/load game data

Display & Graphics

Display Properties

thumby.display.width   # 72 pixels
thumby.display.height  # 40 pixels

Core Display Functions

thumby.display.update()  # Refresh screen - call once per frame
thumby.display.fill(color)  # Fill entire display with color (0 or 1)
thumby.display.setPixel(x, y, color)  # Set individual pixel
thumby.display.getPixel(x, y)  # Get pixel state
thumby.display.drawText(string, x, y, color)  # Draw text at position
thumby.display.drawLine(x1, y1, x2, y2, color)  # Draw line
thumby.display.drawRectangle(x, y, w, h, color)  # Draw rectangle outline
thumby.display.drawFilledRectangle(x, y, w, h, color)  # Draw filled rectangle
thumby.display.blit(bitmapData, x, y, w, h, key, mirrorX, mirrorY)  # Copy bitmap to screen
thumby.display.setFPS(fps)  # Set target frame rate (typically 30)

Best Practice: Frame Updates

Always batch all drawing operations, then call thumby.display.update() once per frame for efficiency.

Sprites

Sprite Constructor

sprite = thumby.Sprite(width, height, bitmapData, x, y, key, mirrorX, mirrorY)

Parameters:

width, height: Sprite dimensions in pixels
bitmapData: Bytearray containing bitmap data
x, y: Initial screen position
key: Transparency key (0 = black is transparent, 1 = white is transparent, -1 = no transparency)
mirrorX, mirrorY: Boolean flags for horizontal/vertical flipping

Sprite Methods

sprite.getFrame()  # Get current frame index
sprite.setFrame(frame)  # Set frame for animation
sprite.x, sprite.y  # Position properties

Optimization Tips:

Keep sprites small (8x8 or 16x16 typical)
Use sprite sheets for animations
Manage frame progression manually in game loop

Button Input

Button Check Methods

thumby.buttonA.pressed()  # True while button held down
thumby.buttonB.pressed()
thumby.buttonU.pressed()  # Up
thumby.buttonD.pressed()  # Down
thumby.buttonL.pressed()  # Left
thumby.buttonR.pressed()  # Right

thumby.buttonA.justPressed()  # True only once per press (for menus/triggers)
thumby.buttonB.justPressed()
# ... same for all buttons

Composite Input Functions

thumby.inputPressed()  # Returns True if any button pressed
thumby.dpadPressed()  # Returns True if any D-pad button pressed
thumby.actionPressed()  # Returns True if A or B pressed

Usage Patterns:

Use .pressed() for continuous actions (movement, holding)
Use .justPressed() for single-trigger actions (menu selection, jump)

Audio

Audio Functions

thumby.audio.play(frequency, duration)  # Play tone (non-blocking)
thumby.audio.playBlocking(frequency, duration)  # Play tone (blocking)
thumby.audio.stop()  # Stop current audio

Limitations:

Simple tone generation only
Keep audio short to maintain responsiveness
Use sparingly due to hardware constraints

Save Data

Save Data API

thumby.saveData.setName("GameName")  # Set unique name for save file
thumby.saveData.setItem("key", value)  # Store value (string/number/list/tuple)
thumby.saveData.getItem("key")  # Retrieve value
thumby.saveData.hasItem("key")  # Check if key exists
thumby.saveData.save()  # Commit changes to persistent storage
thumby.saveData.delItem("key")  # Delete item

Save File Location: /Saves/<GameName>/persistent.json

Example Pattern:

thumby.saveData.setName("HighScore")
highScore = 0
if thumby.saveData.hasItem("highscore"):
    highScore = int(thumby.saveData.getItem("highscore"))

# After game ends
if newScore > highScore:
    thumby.saveData.setItem("highscore", newScore)
    thumby.saveData.save()

Multiplayer Link

The Thumby Link cable enables device-to-device communication:

thumby.link.send(data)  # Send data to connected Thumby
thumby.link.receive()  # Receive data from connected Thumby

File Structure & Organization

Recommended Game Structure

GameName/
├── GameName.py              # Main game file (must match folder name)
├── arcade_title_image.png   # Title image for Thumby Arcade
├── arcade_title_video.webm  # Optional: Title video
└── sprites/                 # Optional: sprite data files

Code Organization Best Practices

Initialization Section: Load saved data, initialize variables

Main Game Loop:

while True:
    # 1. Handle input
    # 2. Update game logic
    # 3. Draw everything
    thumby.display.update()

Function Structure: Separate logic for drawing, input, game state
Naming: Use lowercase for file names and consistent naming

Performance Best Practices

Memory & Speed Optimization

Import only needed submodules instead of full thumby module
Keep sprites minimal - 8x8 pixels for small objects, up to 16x16 for larger
Limit per-frame computations - pre-calculate when possible
Target 30 FPS minimum for responsive gameplay
Batch drawing operations before calling display.update()
Use sprite keys for transparency instead of manual pixel checks

Display Optimization

Screen shows ~12 characters per row of text
Design concise menus and minimal UI
Use abbreviated text and symbols

Audio Optimization

Keep sound effects short (< 500ms typical)
Avoid audio during intense graphics updates
Use non-blocking play() for background effects

Common Game Patterns

Game State Management

STATE_MENU = 0
STATE_PLAYING = 1
STATE_GAMEOVER = 2

gameState = STATE_MENU

while True:
    if gameState == STATE_MENU:
        # Handle menu input and drawing
    elif gameState == STATE_PLAYING:
        # Handle gameplay
    elif gameState == STATE_GAMEOVER:
        # Handle game over screen
    
    thumby.display.update()

Animation Pattern

# Frame counter for animation timing
frameCounter = 0
animationFrame = 0
animationSpeed = 5  # Update every 5 frames

while True:
    frameCounter += 1
    if frameCounter >= animationSpeed:
        frameCounter = 0
        animationFrame = (animationFrame + 1) % numFrames
        sprite.setFrame(animationFrame)
    
    thumby.display.update()

Collision Detection

def checkCollision(x1, y1, w1, h1, x2, y2, w2, h2):
    return (x1 < x2 + w2 and
            x1 + w1 > x2 and
            y1 < y2 + h2 and
            y1 + h1 > y2)

Additional Resources

Official Documentation: https://thumby.us/
API Reference: https://thumby.us/API/Get-Started/
Code Editor: https://code.thumby.us/
Sample Games: https://github.com/TinyCircuits/TinyCircuits-Thumby-Games
Making a Game Tutorial: https://thumby.us/Code-Editor/Making-a-game/
Sprite Documentation: https://thumby.us/API/Sprites/
Graphics Basics: https://thumby.us/API/Graphics/
Button Input: https://thumby.us/API/Buttons/
Save Data: https://thumby.us/API/Save-Files/

Advanced Topics

Thumby BASIC

Alternative to MicroPython for text-based retro programs:

Documentation: https://github.com/TinyCircuits/TinyCircuits-Thumby-Games/blob/master/ThumbyBasic/README.md

Thumby Color (Next Generation)

For the newer color device with enhanced capabilities:

Documentation: https://color.thumby.us
Features 16-bit color, additional buttons, more powerful API

C/C++ Development (Arduino)

Advanced users can use Arduino SDK:

API Reference: https://thumby.us/CCPP/API-Reference/
More control but increased complexity

Development Workflow

Setup: Open Thumby Code Editor in Chrome/Edge
Code: Write MicroPython game code
Test: Use built-in emulator for rapid iteration
Debug: Check display output, button response, save data
Upload: Connect Thumby via USB and upload to device
Refine: Test on actual hardware, adjust timing/controls

Key Constraints & Limitations

Memory: Limited RAM, keep code and assets minimal
Processing: Simple CPU, avoid complex calculations per frame
Display: Monochrome only, 72x40 resolution
Audio: Tone generation only, no complex synthesis
Storage: Limited, design efficient save data structures
Power: Battery-powered, optimize for efficiency

Testing Recommendations

Test in emulator first for rapid iteration
Test on actual hardware for timing, button feel, display clarity
Test battery life for longer play sessions
Test save/load functionality thoroughly
Test edge cases (button mashing, quick resets, etc.)

This document is based on official Thumby SDK documentation from TinyCircuits. For the most up-to-date information, always refer to the official documentation at https://thumby.us/

# Thumby SDK Official Documentation Context This document provides essential context for AI coding agents developing Thumby games and applications based on the official Thumby SDK documentation. ## Thumby Hardware Overview - **Display**: 72x40 pixel monochrome OLED screen - **Controls**: 6 buttons (4-way D-pad: Up, Down, Left, Right + 2 action buttons: A, B) - **Platform**: Tiny keychain-sized gaming device running MicroPython - **Screen Dimensions**: width = 72, height = 40 pixels - **Color**: Binary (0 = black/off, 1 = white/on) ## Development Environment ### Thumby Web Code Editor - **URL**: https://code.thumby.us/ - **Features**: - Live emulation for instant testing - File management (local and device) - Built-in sprite editor - Direct USB upload to device (MicroUSB cable required) - Browser support: Chrome and Edge only - **Usage**: All code is saved locally in browser storage ### API Documentation - **Main Docs**: https://thumby.us/API/Get-Started/ - **Language**: MicroPython - **Import**: `import thumby` ## Core Thumby API Reference ### API Submodules (v1.7+) For optimized performance, import only needed submodules: - `thumbyGraphics` - Graphics and display functions - `thumbyHardware` - Hardware integration - `thumbyButton` - Button input handling - `thumbyAudio` - Sound and audio - `thumbyLink` - Multiplayer link functionality - `thumbySaves` - Save/load game data ### Display & Graphics #### Display Properties ```python thumby.display.width # 72 pixels thumby.display.height # 40 pixels ``` #### Core Display Functions ```python thumby.display.update() # Refresh screen - call once per frame thumby.display.fill(color) # Fill entire display with color (0 or 1) thumby.display.setPixel(x, y, color) # Set individual pixel thumby.display.getPixel(x, y) # Get pixel state thumby.display.drawText(string, x, y, color) # Draw text at position thumby.display.drawLine(x1, y1, x2, y2, color) # Draw line thumby.display.drawRectangle(x, y, w, h, color) # Draw rectangle outline thumby.display.drawFilledRectangle(x, y, w, h, color) # Draw filled rectangle thumby.display.blit(bitmapData, x, y, w, h, key, mirrorX, mirrorY) # Copy bitmap to screen thumby.display.setFPS(fps) # Set target frame rate (typically 30) ``` #### Best Practice: Frame Updates Always batch all drawing operations, then call `thumby.display.update()` once per frame for efficiency. ### Sprites #### Sprite Constructor ```python sprite = thumby.Sprite(width, height, bitmapData, x, y, key, mirrorX, mirrorY) ``` **Parameters:** - `width`, `height`: Sprite dimensions in pixels - `bitmapData`: Bytearray containing bitmap data - `x`, `y`: Initial screen position - `key`: Transparency key (0 = black is transparent, 1 = white is transparent, -1 = no transparency) - `mirrorX`, `mirrorY`: Boolean flags for horizontal/vertical flipping #### Sprite Methods ```python sprite.getFrame() # Get current frame index sprite.setFrame(frame) # Set frame for animation sprite.x, sprite.y # Position properties ``` **Optimization Tips:** - Keep sprites small (8x8 or 16x16 typical) - Use sprite sheets for animations - Manage frame progression manually in game loop ### Button Input #### Button Check Methods ```python thumby.buttonA.pressed() # True while button held down thumby.buttonB.pressed() thumby.buttonU.pressed() # Up thumby.buttonD.pressed() # Down thumby.buttonL.pressed() # Left thumby.buttonR.pressed() # Right thumby.buttonA.justPressed() # True only once per press (for menus/triggers) thumby.buttonB.justPressed() # ... same for all buttons ``` #### Composite Input Functions ```python thumby.inputPressed() # Returns True if any button pressed thumby.dpadPressed() # Returns True if any D-pad button pressed thumby.actionPressed() # Returns True if A or B pressed ``` **Usage Patterns:** - Use `.pressed()` for continuous actions (movement, holding) - Use `.justPressed()` for single-trigger actions (menu selection, jump) ### Audio #### Audio Functions ```python thumby.audio.play(frequency, duration) # Play tone (non-blocking) thumby.audio.playBlocking(frequency, duration) # Play tone (blocking) thumby.audio.stop() # Stop current audio ``` **Limitations:** - Simple tone generation only - Keep audio short to maintain responsiveness - Use sparingly due to hardware constraints ### Save Data #### Save Data API ```python thumby.saveData.setName("GameName") # Set unique name for save file thumby.saveData.setItem("key", value) # Store value (string/number/list/tuple) thumby.saveData.getItem("key") # Retrieve value thumby.saveData.hasItem("key") # Check if key exists thumby.saveData.save() # Commit changes to persistent storage thumby.saveData.delItem("key") # Delete item ``` **Save File Location:** `/Saves/<GameName>/persistent.json` **Example Pattern:** ```python thumby.saveData.setName("HighScore") highScore = 0 if thumby.saveData.hasItem("highscore"): highScore = int(thumby.saveData.getItem("highscore")) # After game ends if newScore > highScore: thumby.saveData.setItem("highscore", newScore) thumby.saveData.save() ``` ### Multiplayer Link The Thumby Link cable enables device-to-device communication: ```python thumby.link.send(data) # Send data to connected Thumby thumby.link.receive() # Receive data from connected Thumby ``` ## File Structure & Organization ### Recommended Game Structure ``` GameName/ ├── GameName.py # Main game file (must match folder name) ├── arcade_title_image.png # Title image for Thumby Arcade ├── arcade_title_video.webm # Optional: Title video └── sprites/ # Optional: sprite data files ``` ### Code Organization Best Practices 1. **Initialization Section**: Load saved data, initialize variables 2. **Main Game Loop**: ```python while True: # 1. Handle input # 2. Update game logic # 3. Draw everything thumby.display.update() ``` 3. **Function Structure**: Separate logic for drawing, input, game state 4. **Naming**: Use lowercase for file names and consistent naming ## Performance Best Practices ### Memory & Speed Optimization 1. **Import only needed submodules** instead of full `thumby` module 2. **Keep sprites minimal** - 8x8 pixels for small objects, up to 16x16 for larger 3. **Limit per-frame computations** - pre-calculate when possible 4. **Target 30 FPS minimum** for responsive gameplay 5. **Batch drawing operations** before calling `display.update()` 6. **Use sprite keys** for transparency instead of manual pixel checks ### Display Optimization - Screen shows ~12 characters per row of text - Design concise menus and minimal UI - Use abbreviated text and symbols ### Audio Optimization - Keep sound effects short (< 500ms typical) - Avoid audio during intense graphics updates - Use non-blocking `play()` for background effects ## Common Game Patterns ### Game State Management ```python STATE_MENU = 0 STATE_PLAYING = 1 STATE_GAMEOVER = 2 gameState = STATE_MENU while True: if gameState == STATE_MENU: # Handle menu input and drawing elif gameState == STATE_PLAYING: # Handle gameplay elif gameState == STATE_GAMEOVER: # Handle game over screen thumby.display.update() ``` ### Animation Pattern ```python # Frame counter for animation timing frameCounter = 0 animationFrame = 0 animationSpeed = 5 # Update every 5 frames while True: frameCounter += 1 if frameCounter >= animationSpeed: frameCounter = 0 animationFrame = (animationFrame + 1) % numFrames sprite.setFrame(animationFrame) thumby.display.update() ``` ### Collision Detection ```python def checkCollision(x1, y1, w1, h1, x2, y2, w2, h2): return (x1 < x2 + w2 and x1 + w1 > x2 and y1 < y2 + h2 and y1 + h1 > y2) ``` ## Additional Resources - **Official Documentation**: https://thumby.us/ - **API Reference**: https://thumby.us/API/Get-Started/ - **Code Editor**: https://code.thumby.us/ - **Sample Games**: https://github.com/TinyCircuits/TinyCircuits-Thumby-Games - **Making a Game Tutorial**: https://thumby.us/Code-Editor/Making-a-game/ - **Sprite Documentation**: https://thumby.us/API/Sprites/ - **Graphics Basics**: https://thumby.us/API/Graphics/ - **Button Input**: https://thumby.us/API/Buttons/ - **Save Data**: https://thumby.us/API/Save-Files/ ## Advanced Topics ### Thumby BASIC Alternative to MicroPython for text-based retro programs: - **Documentation**: https://github.com/TinyCircuits/TinyCircuits-Thumby-Games/blob/master/ThumbyBasic/README.md ### Thumby Color (Next Generation) For the newer color device with enhanced capabilities: - **Documentation**: https://color.thumby.us - Features 16-bit color, additional buttons, more powerful API ### C/C++ Development (Arduino) Advanced users can use Arduino SDK: - **API Reference**: https://thumby.us/CCPP/API-Reference/ - More control but increased complexity ## Development Workflow 1. **Setup**: Open Thumby Code Editor in Chrome/Edge 2. **Code**: Write MicroPython game code 3. **Test**: Use built-in emulator for rapid iteration 4. **Debug**: Check display output, button response, save data 5. **Upload**: Connect Thumby via USB and upload to device 6. **Refine**: Test on actual hardware, adjust timing/controls ## Key Constraints & Limitations - **Memory**: Limited RAM, keep code and assets minimal - **Processing**: Simple CPU, avoid complex calculations per frame - **Display**: Monochrome only, 72x40 resolution - **Audio**: Tone generation only, no complex synthesis - **Storage**: Limited, design efficient save data structures - **Power**: Battery-powered, optimize for efficiency ## Testing Recommendations - **Test in emulator first** for rapid iteration - **Test on actual hardware** for timing, button feel, display clarity - **Test battery life** for longer play sessions - **Test save/load** functionality thoroughly - **Test edge cases** (button mashing, quick resets, etc.) --- *This document is based on official Thumby SDK documentation from TinyCircuits. For the most up-to-date information, always refer to the official documentation at https://thumby.us/*

{ "prompt": "# Thumby SDK Official Documentation Context\n\nThis document provides essential context for AI coding agents developing Thumby games and applications based on the official Thumby SDK documentation.\n\n## Thumby Hardware Overview\n\n- **Display**: 72x40 pixel monochrome OLED screen\n- **Controls**: 6 buttons (4-way D-pad: Up, Down, Left, Right + 2 action buttons: A, B)\n- **Platform**: Tiny keychain-sized gaming device running MicroPython\n- **Screen Dimensions**: width = 72, height = 40 pixels\n- **Color**: Binary (0 = black/off, 1 = white/on)\n\n## Development Environment\n\n### Thumby Web Code Editor\n- **URL**: https://code.thumby.us/\n- **Features**: \n - Live emulation for instant testing\n - File management (local and device)\n - Built-in sprite editor\n - Direct USB upload to device (MicroUSB cable required)\n - Browser support: Chrome and Edge only\n- **Usage**: All code is saved locally in browser storage\n\n### API Documentation\n- **Main Docs**: https://thumby.us/API/Get-Started/\n- **Language**: MicroPython\n- **Import**: `import thumby`\n\n## Core Thumby API Reference\n\n### API Submodules (v1.7+)\nFor optimized performance, import only needed submodules:\n- `thumbyGraphics` - Graphics and display functions\n- `thumbyHardware` - Hardware integration\n- `thumbyButton` - Button input handling\n- `thumbyAudio` - Sound and audio\n- `thumbyLink` - Multiplayer link functionality\n- `thumbySaves` - Save/load game data\n\n### Display & Graphics\n\n#### Display Properties\n```python\nthumby.display.width # 72 pixels\nthumby.display.height # 40 pixels\n```\n\n#### Core Display Functions\n```python\nthumby.display.update() # Refresh screen - call once per frame\nthumby.display.fill(color) # Fill entire display with color (0 or 1)\nthumby.display.setPixel(x, y, color) # Set individual pixel\nthumby.display.getPixel(x, y) # Get pixel state\nthumby.display.drawText(string, x, y, color) # Draw text at position\nthumby.display.drawLine(x1, y1, x2, y2, color) # Draw line\nthumby.display.drawRectangle(x, y, w, h, color) # Draw rectangle outline\nthumby.display.drawFilledRectangle(x, y, w, h, color) # Draw filled rectangle\nthumby.display.blit(bitmapData, x, y, w, h, key, mirrorX, mirrorY) # Copy bitmap to screen\nthumby.display.setFPS(fps) # Set target frame rate (typically 30)\n```\n\n#### Best Practice: Frame Updates\nAlways batch all drawing operations, then call `thumby.display.update()` once per frame for efficiency.\n\n### Sprites\n\n#### Sprite Constructor\n```python\nsprite = thumby.Sprite(width, height, bitmapData, x, y, key, mirrorX, mirrorY)\n```\n\n**Parameters:**\n- `width`, `height`: Sprite dimensions in pixels\n- `bitmapData`: Bytearray containing bitmap data\n- `x`, `y`: Initial screen position\n- `key`: Transparency key (0 = black is transparent, 1 = white is transparent, -1 = no transparency)\n- `mirrorX`, `mirrorY`: Boolean flags for horizontal/vertical flipping\n\n#### Sprite Methods\n```python\nsprite.getFrame() # Get current frame index\nsprite.setFrame(frame) # Set frame for animation\nsprite.x, sprite.y # Position properties\n```\n\n**Optimization Tips:**\n- Keep sprites small (8x8 or 16x16 typical)\n- Use sprite sheets for animations\n- Manage frame progression manually in game loop\n\n### Button Input\n\n#### Button Check Methods\n```python\nthumby.buttonA.pressed() # True while button held down\nthumby.buttonB.pressed()\nthumby.buttonU.pressed() # Up\nthumby.buttonD.pressed() # Down\nthumby.buttonL.pressed() # Left\nthumby.buttonR.pressed() # Right\n\nthumby.buttonA.justPressed() # True only once per press (for menus/triggers)\nthumby.buttonB.justPressed()\n# ... same for all buttons\n```\n\n#### Composite Input Functions\n```python\nthumby.inputPressed() # Returns True if any button pressed\nthumby.dpadPressed() # Returns True if any D-pad button pressed\nthumby.actionPressed() # Returns True if A or B pressed\n```\n\n**Usage Patterns:**\n- Use `.pressed()` for continuous actions (movement, holding)\n- Use `.justPressed()` for single-trigger actions (menu selection, jump)\n\n### Audio\n\n#### Audio Functions\n```python\nthumby.audio.play(frequency, duration) # Play tone (non-blocking)\nthumby.audio.playBlocking(frequency, duration) # Play tone (blocking)\nthumby.audio.stop() # Stop current audio\n```\n\n**Limitations:**\n- Simple tone generation only\n- Keep audio short to maintain responsiveness\n- Use sparingly due to hardware constraints\n\n### Save Data\n\n#### Save Data API\n```python\nthumby.saveData.setName(\"GameName\") # Set unique name for save file\nthumby.saveData.setItem(\"key\", value) # Store value (string/number/list/tuple)\nthumby.saveData.getItem(\"key\") # Retrieve value\nthumby.saveData.hasItem(\"key\") # Check if key exists\nthumby.saveData.save() # Commit changes to persistent storage\nthumby.saveData.delItem(\"key\") # Delete item\n```\n\n**Save File Location:** `/Saves/<GameName>/persistent.json`\n\n**Example Pattern:**\n```python\nthumby.saveData.setName(\"HighScore\")\nhighScore = 0\nif thumby.saveData.hasItem(\"highscore\"):\n highScore = int(thumby.saveData.getItem(\"highscore\"))\n\n# After game ends\nif newScore > highScore:\n thumby.saveData.setItem(\"highscore\", newScore)\n thumby.saveData.save()\n```\n\n### Multiplayer Link\n\nThe Thumby Link cable enables device-to-device communication:\n```python\nthumby.link.send(data) # Send data to connected Thumby\nthumby.link.receive() # Receive data from connected Thumby\n```\n\n## File Structure & Organization\n\n### Recommended Game Structure\n```\nGameName/\n├── GameName.py # Main game file (must match folder name)\n├── arcade_title_image.png # Title image for Thumby Arcade\n├── arcade_title_video.webm # Optional: Title video\n└── sprites/ # Optional: sprite data files\n```\n\n### Code Organization Best Practices\n\n1. **Initialization Section**: Load saved data, initialize variables\n2. **Main Game Loop**: \n ```python\n while True:\n # 1. Handle input\n # 2. Update game logic\n # 3. Draw everything\n thumby.display.update()\n ```\n3. **Function Structure**: Separate logic for drawing, input, game state\n4. **Naming**: Use lowercase for file names and consistent naming\n\n## Performance Best Practices\n\n### Memory & Speed Optimization\n1. **Import only needed submodules** instead of full `thumby` module\n2. **Keep sprites minimal** - 8x8 pixels for small objects, up to 16x16 for larger\n3. **Limit per-frame computations** - pre-calculate when possible\n4. **Target 30 FPS minimum** for responsive gameplay\n5. **Batch drawing operations** before calling `display.update()`\n6. **Use sprite keys** for transparency instead of manual pixel checks\n\n### Display Optimization\n- Screen shows ~12 characters per row of text\n- Design concise menus and minimal UI\n- Use abbreviated text and symbols\n\n### Audio Optimization\n- Keep sound effects short (< 500ms typical)\n- Avoid audio during intense graphics updates\n- Use non-blocking `play()` for background effects\n\n## Common Game Patterns\n\n### Game State Management\n```python\nSTATE_MENU = 0\nSTATE_PLAYING = 1\nSTATE_GAMEOVER = 2\n\ngameState = STATE_MENU\n\nwhile True:\n if gameState == STATE_MENU:\n # Handle menu input and drawing\n elif gameState == STATE_PLAYING:\n # Handle gameplay\n elif gameState == STATE_GAMEOVER:\n # Handle game over screen\n \n thumby.display.update()\n```\n\n### Animation Pattern\n```python\n# Frame counter for animation timing\nframeCounter = 0\nanimationFrame = 0\nanimationSpeed = 5 # Update every 5 frames\n\nwhile True:\n frameCounter += 1\n if frameCounter >= animationSpeed:\n frameCounter = 0\n animationFrame = (animationFrame + 1) % numFrames\n sprite.setFrame(animationFrame)\n \n thumby.display.update()\n```\n\n### Collision Detection\n```python\ndef checkCollision(x1, y1, w1, h1, x2, y2, w2, h2):\n return (x1 < x2 + w2 and\n x1 + w1 > x2 and\n y1 < y2 + h2 and\n y1 + h1 > y2)\n```\n\n## Additional Resources\n\n- **Official Documentation**: https://thumby.us/\n- **API Reference**: https://thumby.us/API/Get-Started/\n- **Code Editor**: https://code.thumby.us/\n- **Sample Games**: https://github.com/TinyCircuits/TinyCircuits-Thumby-Games\n- **Making a Game Tutorial**: https://thumby.us/Code-Editor/Making-a-game/\n- **Sprite Documentation**: https://thumby.us/API/Sprites/\n- **Graphics Basics**: https://thumby.us/API/Graphics/\n- **Button Input**: https://thumby.us/API/Buttons/\n- **Save Data**: https://thumby.us/API/Save-Files/\n\n## Advanced Topics\n\n### Thumby BASIC\nAlternative to MicroPython for text-based retro programs:\n- **Documentation**: https://github.com/TinyCircuits/TinyCircuits-Thumby-Games/blob/master/ThumbyBasic/README.md\n\n### Thumby Color (Next Generation)\nFor the newer color device with enhanced capabilities:\n- **Documentation**: https://color.thumby.us\n- Features 16-bit color, additional buttons, more powerful API\n\n### C/C++ Development (Arduino)\nAdvanced users can use Arduino SDK:\n- **API Reference**: https://thumby.us/CCPP/API-Reference/\n- More control but increased complexity\n\n## Development Workflow\n\n1. **Setup**: Open Thumby Code Editor in Chrome/Edge\n2. **Code**: Write MicroPython game code\n3. **Test**: Use built-in emulator for rapid iteration\n4. **Debug**: Check display output, button response, save data\n5. **Upload**: Connect Thumby via USB and upload to device\n6. **Refine**: Test on actual hardware, adjust timing/controls\n\n## Key Constraints & Limitations\n\n- **Memory**: Limited RAM, keep code and assets minimal\n- **Processing**: Simple CPU, avoid complex calculations per frame\n- **Display**: Monochrome only, 72x40 resolution\n- **Audio**: Tone generation only, no complex synthesis\n- **Storage**: Limited, design efficient save data structures\n- **Power**: Battery-powered, optimize for efficiency\n\n## Testing Recommendations\n\n- **Test in emulator first** for rapid iteration\n- **Test on actual hardware** for timing, button feel, display clarity\n- **Test battery life** for longer play sessions\n- **Test save/load** functionality thoroughly\n- **Test edge cases** (button mashing, quick resets, etc.)\n\n---\n\n*This document is based on official Thumby SDK documentation from TinyCircuits. For the most up-to-date information, always refer to the official documentation at https://thumby.us/*", "variables": [], "notes": "This document provides essential context for AI coding agents developing Thumby games and applications based on the official Thumby SDK documentation.", "metadata": { "source": { "provider": "github-prompts", "repository": "https://github.com/anewcomer/d-bag", "path": ".github/prompts/thumby-official-doc.prompt.md", "ref": "d6d9560eaa68386601028d26d12f95959c120b0a", "url": "https://github.com/anewcomer/d-bag/blob/d6d9560eaa68386601028d26d12f95959c120b0a/.github/prompts/thumby-official-doc.prompt.md", "key": "anewcomer/d-bag/.github/prompts/thumby-official-doc.prompt.md" } } }

About