diff --git a/Keyboard-Layout-and-IME.md b/Keyboard-Layout-and-IME.md
new file mode 100644
index 0000000..5f10d4f
--- /dev/null
+++ b/Keyboard-Layout-and-IME.md
@@ -0,0 +1,37 @@
+Terrarum provides an IME for entering non-Latin languages.
+
+The IME manages two keyboard layouts: the Low Layout and the High Layout. The Low Layout is usually a Latin character layout (e.g. QWERTY, Colemak) and the High Layout is more sophisticated layout for non-Latin. Changing the Low Layout does not affect the High Layout (except for the "phonetic" High Layouts which will read Low Layout).
+
+The user can switch between two layers at any moment.
+
+The layouts are stored in `<assets> or <module base dir>/keylayout/` directory and the following extensions are examined: `.key` for the the Low Layout and `.ime` for the High Layout.
+
+## The Key File (The Low Layout)
+
+**.key** files are non-programmable, Javascript-based and stores the keyboard layout and some metadata.
+
+**.key** files must be formatted as such:
+
+```
+{
+    "n":"US-Intl. Qwerty", // the name of the layout
+    "capslock":"caps", // the capslock mode
+    "t":[ [..], [..], [..]... ] // the actual layout, 256 entries
+}
+```
+
+of which:
+
+- **n**: the name of the keyboard layout in plaintext
+- **capslock**: what does the Caps Lock key should do. "caps" for the ordinary Caps Lock, "back" for the Backspace (e.g. Colemak), and "shift" for the Shift.
+- **t**: the array of Key Symbols, corresponds to the LibGDX keycode. Each keycode gets an array of variable length between 0 up to 4.
+    - Index 0: The base layer (e.g. lowercases)
+    - Index 1: The Shift layer (e.g. uppercases)
+    - Index 2: The AltGr layer (e.g. symbols that require AltGr but not Shift)
+    - Index 3: The AltGr-Shift layer (e.g. symbols that require both AltGr and Shift)
+
+The Key Symbol is just a Javascript String of arbitrary length. Ones surrounded with `<...>` are special symbols that denotes a special key (e.g. media keys).
+
+## The Ime File (The High Layout)
+
+**.ime** files are programmable and Javascript-based 
\ No newline at end of file