key events;

api/init.lua

@@ -259,6 +259,69 @@ return {
         }
       }
     },
+    {
+      name = "keypressed",
+      tag = "callbacks",
+      summary = "Called when a key is pressed.",
+      description = "This callback is called when a key is pressed.",
+      key = "lovr.keypressed",
+      module = "lovr",
+      related = {
+        "lovr.keyreleased",
+        "lovr.textinput"
+      },
+      variants = {
+        {
+          arguments = {
+            {
+              name = "key",
+              type = "KeyCode",
+              description = "The key that was pressed."
+            },
+            {
+              name = "scancode",
+              type = "number",
+              description = "The id of the key (ignores keyboard layout, may vary between keyboards)."
+            },
+            {
+              name = "repeat",
+              type = "boolean",
+              description = "Whether the event is the result of a key repeat instead of an actual press."
+            }
+          },
+          returns = {}
+        }
+      }
+    },
+    {
+      name = "keyreleased",
+      tag = "callbacks",
+      summary = "Called when a key is released.",
+      description = "This callback is called when a key is released.",
+      key = "lovr.keyreleased",
+      module = "lovr",
+      related = {
+        "lovr.keypressed",
+        "lovr.textinput"
+      },
+      variants = {
+        {
+          arguments = {
+            {
+              name = "key",
+              type = "KeyCode",
+              description = "The key that was released."
+            },
+            {
+              name = "scancode",
+              type = "number",
+              description = "The id of the key (ignores keyboard layout, may vary between keyboards)."
+            }
+          },
+          returns = {}
+        }
+      }
+    },
     {
       name = "load",
       tag = "callbacks",
@@ -413,6 +476,36 @@ return {
         "lovr.quit"
       }
     },
+    {
+      name = "textinput",
+      tag = "callbacks",
+      summary = "Called when text has been entered.",
+      description = "This callback is called when text has been entered.\n\nFor example, when `shift + 1` is pressed on an American keyboard, `lovr.textinput` will be called with `!`.",
+      key = "lovr.textinput",
+      module = "lovr",
+      variants = {
+        {
+          arguments = {
+            {
+              name = "text",
+              type = "string",
+              description = "The UTF-8 encoded character."
+            },
+            {
+              name = "code",
+              type = "number",
+              description = "The integer codepoint of the character."
+            }
+          },
+          returns = {}
+        }
+      },
+      related = {
+        "lovr.keypressed",
+        "lovr.keyreleased"
+      },
+      notes = "Some characters in UTF-8 unicode take multiple bytes to encode.  Due to the way Lua works, the length of these strings will be bigger than 1 even though they are just a single character. `lovr.graphics.print` is compatible with UTF-8 but doing other string processing on these strings may require a library.  Lua 5.3+ has support for working with UTF-8 strings."
+    },
     {
       name = "threaderror",
       tag = "callbacks",

api/lovr/callbacks/keypressed.lua

@@ -0,0 +1,27 @@
+return {
+  tag = 'callbacks',
+  summary = 'Called when a key is pressed.',
+  description = 'This callback is called when a key is pressed.',
+  arguments = {
+    {
+      name = 'key',
+      type = 'KeyCode',
+      description = 'The key that was pressed.'
+    },
+    {
+      name = 'scancode',
+      type = 'number',
+      description = 'The id of the key (ignores keyboard layout, may vary between keyboards).'
+    },
+    {
+      name = 'repeat',
+      type = 'boolean',
+      description = 'Whether the event is the result of a key repeat instead of an actual press.'
+    }
+  },
+  returns = {},
+  related = {
+    'lovr.keyreleased',
+    'lovr.textinput'
+  }
+}

api/lovr/callbacks/keyreleased.lua

@@ -0,0 +1,22 @@
+return {
+  tag = 'callbacks',
+  summary = 'Called when a key is released.',
+  description = 'This callback is called when a key is released.',
+  arguments = {
+    {
+      name = 'key',
+      type = 'KeyCode',
+      description = 'The key that was released.'
+    },
+    {
+      name = 'scancode',
+      type = 'number',
+      description = 'The id of the key (ignores keyboard layout, may vary between keyboards).'
+    }
+  },
+  returns = {},
+  related = {
+    'lovr.keypressed',
+    'lovr.textinput'
+  }
+}

api/lovr/callbacks/textinput.lua

@@ -0,0 +1,33 @@
+return {
+  tag = 'callbacks',
+  summary = 'Called when text has been entered.',
+  description = [[
+    This callback is called when text has been entered.
+
+    For example, when `shift + 1` is pressed on an American keyboard, `lovr.textinput` will be
+    called with `!`.
+  ]],
+  arguments = {
+    {
+      name = 'text',
+      type = 'string',
+      description = 'The UTF-8 encoded character.'
+    },
+    {
+      name = 'code',
+      type = 'number',
+      description = 'The integer codepoint of the character.'
+    }
+  },
+  notes = [[
+    Some characters in UTF-8 unicode take multiple bytes to encode.  Due to the way Lua works, the
+    length of these strings will be bigger than 1 even though they are just a single character.
+    `lovr.graphics.print` is compatible with UTF-8 but doing other string processing on these
+    strings may require a library.  Lua 5.3+ has support for working with UTF-8 strings.
+  ]],
+  returns = {},
+  related = {
+    'lovr.keypressed',
+    'lovr.keyreleased'
+  }
+}