Hello everybody, last time I used AppGameKit was as a little know-nothing high schooler. Now I am out of college and living life and wanted to make some games again as a hobby. Here is a plugin I made that was very useful to me and I hope it is to you as well. Currently only supports Windows 32 bit and 64 bit. I compiled the plugin with VS2022 so it should work on anything with Windows 10 or newer. I statically linked in the Visual C++ runtime so no need for your end users to install any runtimes but the trade off is the larger file size. I included the source code (just a single C file) if you want to compile it yourself (and you probably should not be using random DLLs from the internet anyways...). No special compilation instructions needed. Just build as a DLL and you are off to the races. Should compile with any compiler made in the last 20 or more years.
Okay, what does this plugin even do and most importantly why do I need it?
Lets take a step back and I will explain the problem!
The world is a big place with many languages and cultures and many people have different keyboards with different layouts, different keys, etc. For example: I am living in the US but I am from Germany and I still have a German keyboard in my shelf and it includes funny letters like: ä, ü, ö and some strange stuff like my Y is where your Z is on your US keyboard layout. It can get even funnier, the French don't use WASD to move in games. They use ZQSD (called a AZERTY keyboard). If you use the built in AppGameKit functions, this will be a total mess. If you program your game to use WASD then your game will be unplayable for users with a French keyboard as the keys are totally scattered around.
Here is the first important lesson: AppGameKit does not care WHERE a key is, only WHAT symbol is on the key. So if you ask if for the W key, it will go find which key has a little W printed on it and not care where it is. This is great for most apps! It means you can handle text input without needing to worry about symbol is on the pressed key, it will always be a W! It works very very poorly for games however. With a game, I want my WASD keys for movement to be next to each other similar to the arrow keys. There is no importance in WHAT symbol is on a key but WHERE the keys are. I want French users to play with ZQSD.
Now, I could detect the system language and check for different keys but this does not work because the user might have their language set to something other than their keyboard layout (for example: me, I have Windows in German but normally use a US keyboard). There is also the problem that there are many many languages and many many keyboard layouts. I can't possibly program them all in advance!
Now comes the second part of the lesson: scan codes! Scan codes are different from key codes because the symbol on the key does not matter. With a scan code, I just look up WHERE the key is. So the physical key that is a W key for your US layouts has the scan code: 0x0011. This means I can use the scan codes to always have the right keys! If a French user plays my game, their game will automatically work with ZQSD!! No work needed for us to do that! And US players will automatically have WASD. This works great!
The sad part is that AppGameKit has no concept of scan codes at all
So this is what my plugin solves. All it does is translate scan codes to key codes. It does not provide any input functions at all, it does not check if a key is pressed, etc. You give it a scan code and it tells you what AppGameKit key to use from this list:
https://www.appgamekit.com/documentation/guides/scancodes.htm
How do I use this plugin?
It is very easy.
You call the only function in the DLL: GetUserKey with a key code from
https://www.appgamekit.com/documentation/guides/scancodes.htm and it gives you back what key is actually located there on the user's keyboard. Basically, look at a standard US keyboard layout. Pick the location of the key that you want to use, use the AppGameKit key code from the above link and the function will give back to you the key code that is located there. Basically, it auto translates the key code.
Here is a short example of how to use this:
In this example we check if the Z key is pressed. We do this because on a German keyboard, a Z and a Y are swapped. So if you run this example program
on a computer with a German keyboard, you actually press the Y key to get the message in the example to show up.
#import_plugin ScanCodeTranslator as SCT
#constant KEY_Z 90
iKeyCode = SCT.GetUserKey(KEY_Z)
do
if GetRawKeyPressed(iKeyCode) then Message("The key with the Z scan code was pressed!")
Sync()
loop
Only more testers are needed right now. I only have a US and German keyboard to test with. I used the Windows Win32 API to translate the keys so it should automatically work with any keyboard layout, no need to program them in. However, I don't know anything about languages that don't have at least a semi-latin Alphabet like Russian for example. If you have a Russian keyboard or a non-Latin keyboard. Please try out my plugin and report back! Thank you!
License:
I am giving this to the public domain and take no responsibility of any kind for this plugin. Use at your own risk and I don't claim this to be fit for any purpose implied or otherwise.
Thank you for your time!
Sorry for the cringy user name. I was young and dumb...
