more documentation

default f11 key behavior
add a "things to know" page to docs
more readable documentation for functions

.pre-commit-config.yaml

@@ -1,6 +1,7 @@
 repos:
-- repo: https://github.com/pre-commit/mirrors-clang-format
-  rev: v16.0.5
-  hooks:
-  - id: clang-format
-    files: \.(c|cc|cpp|h|hpp|cxx|hh|hpp|tpp)$
+  - repo: https://github.com/pre-commit/mirrors-clang-format
+    rev: v16.0.5
+    hooks:
+      - id: clang-format
+        files: \.(c|cc|cpp|h|hpp|cxx|hh|hpp|tpp)$
+        exclude: ^example/

docs/getting_started/create_window.rst

@@ -49,4 +49,4 @@ Let's break down the key components that make this program function:
     Think of it as flipping the pages of a book—ensuring smooth, sequential updates for the user.
 
 This template establishes a foundation for more advanced game logic and rendering.
-In-depth tutorials on the next page cover the more intricate aspects of the Kraken Engine.
+In-depth tutorials in the next section cover the more intricate aspects of the Kraken Engine.

docs/index.rst

@@ -44,7 +44,8 @@ We’re excited to see how you push the boundaries of creativity with the Kraken
     :maxdepth: 1
     :caption: Manual
 
-    tutorials/index
+    manual/things_to_know
+    manual/tutorials
 
 .. toctree::
     :hidden:
@@ -69,6 +70,7 @@ We’re excited to see how you push the boundaries of creativity with the Kraken
     reference/constants
     reference/controller
     reference/draw
+    reference/input
     reference/key
     reference/math
     reference/mouse

docs/manual/things_to_know.rst

@@ -0,0 +1,57 @@
+Things To Know
+==============
+
+This section contains information that you should be aware of when using Kraken Engine.
+
+Constant Prefixes
+~~~~~~~~~~~~~~~~~
+
+When working with keyboard, mouse, and controller input, you will notice that the constants for the keys and buttons have prefixes.
+The prefixes are as follows:
+
+- ``K_`` for keyboard keycode constants
+- ``S_`` for keyboard scancode constants
+- ``M_`` for mouse button constants
+- ``C_`` for controller button constants
+
+For example, to check if the ``A`` button on a controller is pressed, you would use the following code:
+
+.. code-block:: cpp
+
+    if (kn::controller::isPressed(kn::C_A)) {
+        std::cout << "A button is pressed!" << std::endl;
+    }
+
+Keycode VS Scancode
+~~~~~~~~~~~~~~~~~~~
+
+Kraken Engine uses keycodes and scancodes to represent keyboard input.
+Keycodes are the character that the key represents, while scancodes are the physical location of the key on the keyboard.
+For example, the ``A`` key on a QWERTY keyboard has a keycode of ``K_a`` and a scancode of ``S_a``.
+
+If you are unsure which one to use, it is recommended to use keycodes in the event loop and scancodes for gameplay input.
+
+Here is a comparison of keycodes and scancodes for different scenarios:
+
+.. list-table::
+    :widths: 25 50 50
+    :header-rows: 1
+
+    * - Scenario
+      - Keycode (``K_``)
+      - Scancode (``S_``)
+    * - Menu navigation
+      - ✅ Layout-specific (intuitive keys)
+      - ❌ Might mismatch user expectations
+    * - Text input
+      - ✅ Matches user's layout
+      - ❌ Breaks for non-QWERTY layouts
+    * - Gameplay movement
+      - ❌ Layout-dependent inconsistency
+      - ✅ Consistent across layouts
+    * - Debug tools
+      - ❌ User layout might vary
+      - ✅ Always maps to physical key
+
+
+.. note:: This page is a work in progress and will be updated as more information becomes available.

docs/reference/controller.rst

@@ -18,7 +18,7 @@ Usage
 .. code-block:: cpp
 
     // Get the vector of the left joystick
-    kn::Vec2 leftJoystick = kn::controller::getLeftJoystick();
+    kn::math::Vec2 leftJoystick = kn::controller::getLeftJoystick();
 
     // Change the joysticks' dead zones
     kn::controller::setDeadZone(0.2f);
@@ -28,8 +28,8 @@ Usage
         // Do something
     }
 
-    // Check if the A button is pressed
-    if (kn::controller::isPressed(kn::CONTROLLER_A)) {
+    // Check if the A (bottom) button is pressed
+    if (kn::controller::isPressed(kn::C_A)) {
         // Do something
     }
 
@@ -49,3 +49,5 @@ Functions
 .. doxygenfunction:: kn::controller::setDeadZone
 
 .. doxygenfunction:: kn::controller::getDeadZone
+
+.. note:: Functions for getting controller buttons that were just pressed or just released are planned for the future.

docs/reference/input.rst

@@ -0,0 +1,86 @@
+input
+=====
+
+.. warning::
+
+    This namespace is still in development and is subject to change at any time.
+
+Description
+-----------
+
+The **input** namespace lets you create binds for different kinds of input.
+
+Usage
+-----
+
+.. code-block:: cpp
+
+    /* Bind the 'left' action to:
+        - The 'a' key
+        - The left arrow key
+        - The left stick (negative direction) on a controller
+    */
+    kn::input::bind(
+        "left",
+        {
+            kn::InputAction(kn::S_a),
+            kn::InputAction(kn::S_LEFT),
+            kn::InputAction(kn::C_AXIS_LEFTX, false),
+        }
+    );
+
+    /* Bind the 'right' action to:
+        - The 'd' key
+        - The right arrow key
+        - The left stick (positive direction) on a controller
+    */
+    kn::input::bind(
+        "right",
+        {
+            kn::InputAction(kn::S_d),
+            kn::InputAction(kn::S_RIGHT),
+            kn::InputAction(kn::C_AXIS_LEFTX, true),
+        }
+    );
+
+    /* Bind the 'jump' action to:
+        - The space key
+        - The 'a' button on a controller
+    */
+    kn::input::bind(
+        "jump",
+        {
+            kn::InputAction(kn::S_SPACE),
+            kn::InputAction(kn::C_A),
+        }
+    );
+
+    // Check if the 'jump' action is pressed
+    if (onGround) {
+        if (kn::input::isPressed("jump")) {
+            onGround = false;
+            // Handle jump action
+        }
+    }
+
+    // Get the direction of the 'left' and 'right' actions
+    const double xDirection = kn::input::getDirection("left", "right").x;
+
+Members
+-------
+
+.. doxygenstruct:: kn::InputAction
+    :members:
+
+Functions
+---------
+
+.. doxygenfunction:: kn::input::bind
+
+.. doxygenfunction:: kn::input::unbind
+
+.. doxygenfunction:: kn::input::getDirection
+
+.. doxygenfunction:: kn::input::isPressed
+
+.. note:: Functions for getting input actions that were just pressed or just released are planned for the future.

docs/reference/key.rst

@@ -5,14 +5,7 @@ Description
 -----------
 
 The **key** namespace contains functions to handle input from the keyboard.
-The two types of key codes are `scancodes` and `keycodes`.
-Scancodes are the physical location of the key on the keyboard.
-Keycodes are the character that the key represents.
-For example, 'W' has a scancode of ``kn::S_w`` and a keycode of ``kn::K_w``.
-
-Keycodes are more for text input, while scancodes are more for game input.
-
-.. note:: A function similar to the removed ``kn::input::getVector`` will eventually be added to this namespace.
+If you aren't familiar with the usage of keycodes and scancodes, please refer to the `Things To Know <../manual/things_to_know.html>`_ section.
 
 Usage
 -----
@@ -27,31 +20,9 @@ Usage
         // Handle 'W' key press.
     }
 
-    // Bind keys to the name "up".
-    kn::key::bind("up", {kn::S_w, kn::S_UP});
-
-    // Check if any of the "up" binds are pressed.
-    if (kn::key::isPressed("up")) {
-        // Handle "up" bind.
-    }
-
-    // Make three more binds for left, right, and down.
-    kn::key::bind("left", {kn::S_a, kn::S_LEFT});
-    kn::key::bind("right", {kn::S_d, kn::S_RIGHT});
-    kn::key::bind("down", {kn::S_s, kn::S_DOWN});
-
-    // Get the direction of the four binds.
-    auto direction = kn::key::getDirection("left", "right", "up", "down");
-
 Functions
 ---------
 
 .. doxygenfunction:: kn::key::getPressed
 
-.. doxygenfunction:: kn::key::isPressed
-
-.. doxygenfunction:: kn::key::bind
-
-.. doxygenfunction:: kn::key::unbind
-
-.. doxygenfunction:: kn::key::getDirection
+.. note:: Functions for getting keys that were just pressed or just released are planned for the future.

docs/reference/mouse.rst

@@ -12,7 +12,8 @@ Usage
 .. code-block:: cpp
 
     // Check if the user left clicked.
-    if (kn::mouse::isPressed(kn::MOUSE_LEFT)) {
+    const auto mousePressed = kn::mouse::getPressed();
+    if (mousePressed == kn::MOUSE_LEFT) {
         // Handle left mouse button press.
     }
 
@@ -25,4 +26,6 @@ Functions
 
 .. doxygenfunction:: kn::mouse::getPos
 
-.. doxygenfunction:: kn::mouse::isPressed
+.. doxygenfunction:: kn::mouse::getPressed
+
+.. note:: Functions for getting mouse buttons that were just pressed or just released are planned for the future.

docs/reference/window.rst

@@ -7,6 +7,8 @@ Description
 The window namespace provides functions to create and manage a window.
 It provides methods to draw onto the screen, get input events, and manage the window's properties.
 
+You can find an example of window usage in the `Creating a Window <../getting_started/create_window.html>`_ guide.
+
 Variables
 ---------
 

example/main.cpp

@@ -10,20 +10,29 @@ int main()
 
     constexpr kn::Color bgColor = {21, 18, 37, 255};
 
-    kn::input::bind("left", {
-                                kn::InputAction(kn::S_a),
-                                kn::InputAction(kn::S_LEFT),
-                                kn::InputAction(kn::C_AXIS_LEFTX, false),
-                            });
-    kn::input::bind("right", {
-                                 kn::InputAction(kn::S_d),
-                                 kn::InputAction(kn::S_RIGHT),
-                                 kn::InputAction(kn::C_AXIS_LEFTX, true),
-                             });
-    kn::input::bind("jump", {
-                                kn::InputAction(kn::S_SPACE),
-                                kn::InputAction(kn::C_A),
-                            });
+    kn::input::bind(
+        "left",
+        {
+            kn::InputAction(kn::S_a),
+            kn::InputAction(kn::S_LEFT),
+            kn::InputAction(kn::C_AXIS_LEFTX, false),
+        }
+    );
+    kn::input::bind(
+        "right",
+        {
+            kn::InputAction(kn::S_d),
+            kn::InputAction(kn::S_RIGHT),
+            kn::InputAction(kn::C_AXIS_LEFTX, true),
+        }
+    );
+    kn::input::bind(
+        "jump",
+        {
+            kn::InputAction(kn::S_SPACE),
+            kn::InputAction(kn::C_A),
+        }
+    );
 
     const kn::TileMap tileMap("../example/assets/room.tmx");
 

include/AnimationController.hpp

@@ -47,7 +47,7 @@ class AnimationController final
      * @param frameSize The size of each frame in the sprite sheet.
      * @param fps The frame rate of the animation.
      *
-     * @return true if the setup was successful, false otherwise.
+     * @return ``true`` if the setup was successful, ``false`` otherwise.
      */
     [[maybe_unused]] bool addAnim(const std::string& name, const std::string& filePath,
                                   const math::Vec2& frameSize, int fps);
@@ -64,7 +64,7 @@ class AnimationController final
      *
      * @param name The name of an added animation.
      *
-     * @return true if the animation was successfully changed, false otherwise.
+     * @return ``true`` if the animation was successfully changed, ``false`` otherwise.
      */
     [[maybe_unused]] bool setAnim(const std::string& name);
 
@@ -88,7 +88,7 @@ class AnimationController final
     /**
      * @brief Check if the current animation playing is finished.
      *
-     * @return true if the animation is finished, false otherwise.
+     * @return ``true`` if the animation is finished, ``false`` otherwise.
      */
     [[nodiscard]] bool isFinished();