You’re absolutely right. I need to provide documentation for this, and I’ll write that up tonight. In the meantime, explore the recipes I’ve published and you might be able to deduce what you need.
In short, Alerts are intended to play non-looping, one-shot animations like the ones in inside the /wifi folder on your microSD card (e.g. /00system/wifi/email). Alerts are cool because they flash the screen yellow before the animation, play, and then resume the previously playing animation exactly where it was.
Play simply plays the animation you pass, stopping the currently playing animation and not flashing the screen.
In either case, you can pass any animation (e.g. /bird, /dance, /00system/wifi/twitter). Just be careful with Alerts because if you pass it a looping animation, it will loop forever! 🙂