I'm confused as to how this differs from IsKeyPressed. It looks like it's more transient and only returns true during a single frame when the hit is first hit, so you don't need your own variable to record whether you processed it, but it also looks like you could easily miss the event.The name makes it look like a new block type, so I wonder if it was originally intended to be one, but it couldn't be done that way.
When would you use each one?
I use OnKeyDown and OnControlDown a lot, and almost never IsKeypressed. You will want to use the former in every situation when you want something to happen due to the player pressing a key. The documentation is a bit misleading: The OnKeyDown returns true the first frame
it is called after a key is pressed, so if your script only runs once every 10th frame, you will still not miss it.
if OnKeyDown 50 doSomethingendif
is the equivalent to
short key_down...if IsKeyPressed 50 if key_down == 0 set key_down to 1 doSomething endifelse set key_down to 0endif
As you see, the former is much simpler and clearer.