Updated Keyboard Layout and IME (markdown)

Keyboard-Layout-and-IME.md

@@ -1,12 +1,12 @@
 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 IME manages two keyboard layouts: the Low Layer and the High Layer. The Low Layer is usually a Latin character layout (e.g. QWERTY, Colemak) and the High Layer is more sophisticated layout for non-Latin. Changing the Low Layer does not affect the High Layer (except for the "phonetic" High Layers which will read Low Layer).
 
 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 layouts are stored in `<assets> or <module base dir>/keylayout/` directory and the following extensions are examined: `.key` for the the Low Layer and `.ime` for the High Layer.
 
-## The Key File (The Low Layout)
+## The Key File (The Low Layer)
 
 **.key** files are non-programmable, Javascript-based and stores the keyboard layout and some metadata.
 
@@ -32,6 +32,44 @@ of which:
 
 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)
+## The Ime File (The High Layer)
 
-**.ime** files are programmable and Javascript-based 
+**.ime** files are programmable variant of .key file and defines how the keyboard layout must behave when the user pushes a key.
+
+When an IME receives a key press, it can either *accept* or *reject* the key input.
+
+**.ime** files must be formatted as such:
+
+```
+let states = {
+    "keylayouts": ..., // same format as the .key files' "t" key
+    "code": 0, // used internally. Write 1 if the character is being composed, 0 if not
+    "hasDeadKey": false, // if this keyboard layout has deadkeys
+} // note: the states object is technically optional, but you *will* want to use it
+return Object.freeze({
+    "n":"두벌식 표준", // the name of the layout
+    "v":"none", // candidate mode. "many" for layouts that require candidates (e.g. Chinese and Japanse), "none" if candidates are not required
+    "c":"CuriousTo\uA75Bvald", // the copyright string
+    "m":"rewrite", // the operation mode. Use one of "rewrite" or "candidates"
+    "t":states.keylayouts.map(it => [it[0],it[1]]), // keyboard layout. Only used by the ingame config UI to show the layout info
+    "l":"koKR", // the language associated with the layout
+    "accept": (headkey, shiftin, altgrin) => {
+        ...
+        return [arg, keysymbol]
+    }, // a function that accepts a key input that returns an array
+    "backspace": () => {
+        ...
+        return keysymbol
+    }, // a function that is called when the backspace key was down that returns a Key Symbol
+    "end": () => {
+        ...
+        return keysymbol
+    }, // a function that is called when a composing is being cancelled that returns a Key Symbol
+    "reset": () => { ... }, // a function that resets the IME's internal state
+    "composing": () => { return states.code != 0 } // a function that returns `true` if the IME is in the middle of composing a character
+})
+```
+
+The interpretation of the `arg` of the `accept` function is different for the Candidates and the Rewrite mode. On Rewrite mode, the `arg` is a number that indicates how many characters on the text buffer must be deleted before adding a Key Symbol; on Candidates mode, it's a "\x1E-separated" string of candidates.
+
+Which key being a backspace depends on the Low Layer: if your Low Layer is Colemak and the Caps Lock is held while the High Layer is active, the `backspace` function will be invoked.