---
name: Cute Framework
description: >
  Use when the user asks about: game development, making games, cute framework, CF,
  cf_make_app, cf_app_update, game loop, sprite rendering, draw sprite, animation,
  collision detection, intersect, overlap, keyboard input, mouse input, gamepad,
  draw shapes, draw text, render, Aseprite, audio, sound effects, project setup,
  new game, create project, CMake, cmake setup, start game project, C++ game, C game
version: 1.2.0
---

# Cute Framework Game Development

Cute Framework (CF) is a lightweight 2D game development framework in C. This skill helps you build games efficiently using CF's APIs.

## Quick Reference

| Concept | Key Functions | Notes |
|---------|--------------|-------|
| Project Setup | CMake + FetchContent | See `references/project-setup.md` |
| App Setup | `cf_make_app`, `cf_destroy_app` | Initialize once at startup |
| Game Loop | `cf_app_update`, `cf_app_draw_onto_screen` | Call every frame |
| Drawing | `cf_draw_*` functions | Push/pop for state management |
| Sprites | `cf_make_sprite`, `cf_sprite_update`, `cf_draw_sprite` | Load from Aseprite |
| Input | `cf_key_*`, `cf_mouse_*` | Polled each frame |
| Collision | `cf_*_to_*` intersection functions | Shape-based detection |
| Audio | `cf_audio_load_*`, `cf_play_sound` | OGG/WAV support |

## Getting Started

To create a new CF project, you need:
- CMake 3.28+ and a C++20 compiler
- A `CMakeLists.txt` that fetches CF via FetchContent
- A main source file (C or C++ API)

See `references/project-setup.md` for complete setup instructions and `examples/project-setup/` for starter templates.

## Coordinate System

- **Origin**: Center of screen (0, 0)
- **Y-axis**: Increases **upward** (mathematical convention)
- **Resolution**: User-defined (e.g., 640x480)

## Basic Game Structure

```cpp
#include <cute.h>

int main(int argc, char* argv[]) {
    // Create window
    cf_make_app("My Game", 0, 0, 0, 640, 480,
                CF_APP_OPTIONS_WINDOW_POS_CENTERED_BIT, argv[0]);

    while (cf_app_is_running()) {
        cf_app_update(NULL);  // Process input, advance time

        // Your game logic here

        cf_app_draw_onto_screen();  // Present frame
    }

    cf_destroy_app();
    return 0;
}
```

## Drawing Basics

CF uses a **push/pop pattern** for draw state. Always pop what you push!

```cpp
// Draw a red circle
cf_draw_push_color(cf_color_red());
cf_draw_circle(V2(0, 0), 50.0f, 1.0f);
cf_draw_pop_color();

// Draw text
cf_draw_text("Hello!", V2(-50, 0), -1);
```

### Draw State Functions
- `cf_draw_push_color` / `cf_draw_pop_color` - Tint color
- `cf_draw_push_antialias` / `cf_draw_pop_antialias` - Smoothing
- `cf_draw_push_layer` / `cf_draw_pop_layer` - Z-ordering

## Sprite Animation

Load sprites from Aseprite files (`.ase`/`.aseprite`):

```cpp
CF_Sprite sprite = cf_make_sprite("player.ase");
cf_sprite_play(&sprite, "idle");

// In game loop:
cf_sprite_update(&sprite);
cf_draw_sprite(&sprite);
```

## Input Handling

```cpp
// Keyboard
if (cf_key_down(CF_KEY_SPACE)) {
    // Space held down
}
if (cf_key_just_pressed(CF_KEY_ESCAPE)) {
    // Escape just pressed this frame
}

// Mouse
CF_V2 mouse_pos = cf_mouse_position();
if (cf_mouse_just_pressed(CF_MOUSE_BUTTON_LEFT)) {
    // Left click
}
```

## Collision Detection

CF provides shape-based collision with `cf_X_to_Y` functions:

```cpp
CF_Circle player = cf_make_circle(player_pos, 20.0f);
CF_Aabb enemy = cf_make_aabb(enemy_pos, 30.0f, 30.0f);

if (cf_circle_to_aabb(player, enemy)) {
    // Collision detected!
}
```

### Common Collision Shapes
- `CF_Circle` - Circular hitbox
- `CF_Aabb` - Axis-aligned bounding box
- `CF_Capsule` - Rounded rectangle
- `CF_Poly` - Convex polygon

## Best Practices

1. **Always use push/pop pairs** for draw state changes
2. **Update sprites every frame** with `cf_sprite_update`
3. **Use `CF_DELTA_TIME`** for frame-independent movement
4. **Check `cf_app_is_running()`** in your main loop
5. **Load resources at startup**, not during gameplay

## Common Pitfalls

- Forgetting to call `cf_app_draw_onto_screen()` - nothing renders
- Not popping draw state - affects all subsequent draws
- Using pixel coordinates - CF uses world coordinates centered at origin
- Forgetting `cf_sprite_update` - animations don't play

## Using MCP Documentation Tools

This plugin includes an MCP server with comprehensive CF documentation. Use these tools:

| Tool | Purpose | Example |
|------|---------|---------|
| `mcp__cf-mcp__search` | Find functions/structs by keyword | Search "sprite animation" |
| `mcp__cf-mcp__get_details` | Get full docs for specific item | Get details for "cf_make_sprite" |
| `mcp__cf-mcp__get_topic` | Read conceptual guides | Get topic "drawing" |
| `mcp__cf-mcp__find_related` | Discover related functions | Find related to "CF_Sprite" |
| `mcp__cf-mcp__list_category` | Browse by category | List "draw" category |

### Recommended Workflow

1. Start with `search` to find relevant functions
2. Use `get_details` for function signatures and parameters
3. Read `get_topic` for conceptual understanding
4. Check `find_related` to discover helper functions

## References

See the `references/` directory for detailed documentation:
- `project-setup.md` - Creating new projects, CMake, C vs C++ API
- `core.md` - App lifecycle, game loop, time
- `draw.md` - Shapes, sprites, text rendering
- `input.md` - Keyboard, mouse, gamepad
- `collision.md` - Collision shapes and detection
- `audio.md` - Music and sound effects
- `sprites.md` - Aseprite loading, animations

## Examples

See the `examples/` directory for working code:
- `examples/project-setup/` - CMakeLists.txt, C and C++ starter templates
- `examples/core/` - Basic app setup, game loop patterns
- `examples/rendering/` - Drawing shapes and sprites
- `examples/input/` - Handling player input
- `examples/collision/` - Collision detection