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:

entity = mcrfpy.Entity(grid_pos=(10, 7), texture=texture, sprite_index=84)

Wrong:

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):

scene = mcrfpy.Scene("name")
scene.children.append(frame)
scene.on_key = handler
scene.activate()

Deprecated → Modern:

# 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:

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:

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

Deprecated:

mcrfpy.setTimer("name", callback, milliseconds)  # Wrong signature too

---

Color API

Always use mcrfpy.Color():

frame.fill_color = mcrfpy.Color(255, 0, 0)     # CORRECT
frame.fill_color = mcrfpy.Color(255, 0, 0, 128)  # With alpha

Tuples no longer work:

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