unhardcode and self-document more resource/smudge parameters
document engine limitations