McRogueFace/tests/docs/API_FINDINGS.md

# McRogueFace API Test Findings
*Generated by Frack, January 14, 2026*

## Summary

Tested code snippets from docs site against actual runtime API.
Tests created in `/tests/docs/` with screenshots in `/tests/docs/screenshots/`.

---

## Entity Constructor

**Correct:**
```python
entity = mcrfpy.Entity(grid_pos=(10, 7), texture=texture, sprite_index=84)
```

**Wrong:**
```python
entity = mcrfpy.Entity(pos=(10, 7), ...)  # FAILS - no 'pos' kwarg
entity = mcrfpy.Entity(grid_x=10, grid_y=7, ...)  # FAILS - no separate kwargs
```

---

## Scene API

**Modern (WORKS):**
```python
scene = mcrfpy.Scene("name")
scene.children.append(frame)
scene.on_key = handler
scene.activate()
```

**Deprecated → Modern:**
```python
# OLD                          → NEW
mcrfpy.createScene("name")     → scene = mcrfpy.Scene("name")
mcrfpy.sceneUI("name")         → scene.children
mcrfpy.setScene("name")        → scene.activate()
mcrfpy.keypressScene(fn)       → scene.on_key = fn
mcrfpy.currentScene()          → mcrfpy.current_scene  # property, not function!
```

---

## Grid.at() Signature

Both work:
```python
point = grid.at((x, y))  # Tuple - documented
point = grid.at(x, y)    # Separate args - also works!
```

---

## Animation System

**Works:**
- `x`, `y`, `w`, `h` properties animate correctly
- Callbacks fire as expected
- Multiple simultaneous animations work
- Easing functions work

**Does NOT work:**
- `opacity` - property exists, can set directly, but animation ignores it

---

## Timer API

**Modern:**
```python
timer = mcrfpy.Timer("name", callback, seconds)
# Callback signature: def callback(timer, runtime):
```

**Deprecated:**
```python
mcrfpy.setTimer("name", callback, milliseconds)  # Wrong signature too
```

---

## Color API

Always use `mcrfpy.Color()`:
```python
frame.fill_color = mcrfpy.Color(255, 0, 0)     # CORRECT
frame.fill_color = mcrfpy.Color(255, 0, 0, 128)  # With alpha
```

Tuples no longer work:
```python
frame.fill_color = (255, 0, 0)  # FAILS
```

---

## Available Globals

**All exist:**
- `mcrfpy.default_texture` - Texture for kenney_tinydungeon.png
- `mcrfpy.default_font` - Font for JetBrains Mono
- `mcrfpy.default_fov` - (default FOV settings)

---

## Files Requiring Updates

1. `quickstart.md` - All 4 code blocks use deprecated API
2. `features/scenes.md` - "Procedural API" section entirely deprecated
3. `features/animation.md` - opacity examples don't work
4. Any file using `setTimer`, `createScene`, `sceneUI`, `setScene`, `keypressScene`

---

## Test Files Created

| Test | Status | Notes |
|------|--------|-------|
| test_quickstart_simple_scene.py | PASS | |
| test_quickstart_main_menu.py | PASS | |
| test_quickstart_entities.py | PASS | Uses grid_pos= |
| test_quickstart_sprites.py | PASS | |
| test_features_animation.py | PASS | opacity test skipped |
| test_features_scenes.py | PASS | Documents deprecated API |
| test_entity_api.py | INFO | Verifies grid_pos= works |