From 2ca0a25e742e4d4d9161a1d73b3b5f3790f16c0a Mon Sep 17 00:00:00 2001
From: Kildemal <kildemal@protonmail.com>
Date: Sat, 28 Mar 2026 13:37:08 +0530
Subject: [PATCH] docs(quickstart): add quickstart feature documentation

---
 docs/SUMMARY.md              |  1 +
 docs/tutorials/quickstart.md | 88 ++++++++++++++++++++++++++++++++++++
 2 files changed, 89 insertions(+)
 create mode 100644 docs/tutorials/quickstart.md

diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
index 06f4b8e5c0..6d1fd83a49 100644
--- a/docs/SUMMARY.md
+++ b/docs/SUMMARY.md
@@ -48,6 +48,7 @@
   - [How to use FRLG](tutorials/how_to_frlg.md)
   - [How to delete vanilla maps](tutorials/how_to_delete_vanilla_maps.md)
   - [How to use Map Previews](tutorials/how_to_map_preview_screen.md)
+  - [Quickstart Documentation](tutorials/quickstart.md)
 - [Changelog](./CHANGELOG.md)
     - [1.15.x]()
         - [Version 1.15.0](changelogs/1.15.x/1.15.0.md)
diff --git a/docs/tutorials/quickstart.md b/docs/tutorials/quickstart.md
new file mode 100644
index 0000000000..2a20942a80
--- /dev/null
+++ b/docs/tutorials/quickstart.md
@@ -0,0 +1,88 @@
+
+# Quickstart
+
+Quickstart is a developer convenience feature that allows the user to start a new game from the title screen, skipping the Main Menu and the Birch/Oak intros. In Emerald the player is immediately dropped into the opening truck sequence while in FRLG the player is warped straight into their room.
+
+> **NOTE:** Quickstart is a development only feature and is therefore automatically disabled on release builds.
+
+## Details
+
+Quickstart is enabled by default. It can be turned off using the provided configuration option. It is automatically disabled in release builds.
+
+To use Quickstart press `SELECT` from the title screen to immediately start a new game. The player's name is set to the English canon name (and in FRLG the rival as well). The player's gender is chosen randomly (this can be configured).
+
+#### Player Names
+
+| Game | Male | Female |
+| --------------- | --------------- | --------------- |
+| **Emerald** | BRENDAN | MAY |
+| **FRLG** | RED | LEAF |
+
+The FRLG Rival is named **BLUE**.
+
+#### Hud Element
+
+When Quickstart is enabled a small HUD element is shown on the title screen (this can be disabled). This is displayed as a `64x32` sprite at the top-right corner of the screen. The image dimensions are only `64x16` however but the GBA does not support sprites of those dimensions.
+
+**Source File** : `graphics/quickstart/quickstart_hud.png`
+
+![Quickstart HUD](https://i.ibb.co/G4hhwvmy/quickstart-hud.png)
+
+The same sprite is used for Fire Red, Leaf Green and Emerald. Each game has it's own palette in the `graphics/quickstart/` directory.
+
+## Configuration
+
+The configuration options are briefly covered below.
+
+| Option              | Values                                      | Usage |
+|--------------------|---------------------------------------------|------- |
+| **`ENABLE_QUICKSTART`**  | `TRUE` / `FALSE` | Enables quickstart in dev builds.<br>Always disabled in release builds. |
+| **`QUICKSTART_HUD`**     | `TRUE` / `FALSE`| Shows a small HUD when quickstart is enabled. No effect otherwise. |
+| **`QUICKSTART_GENDER`**  | `GENDER_MALE`, `GENDER_FEMALE`, `GENDER_RANDOM` | Sets player gender for quickstart.<br>`RANDOM` = 50% chance for `MALE`/`FEMALE`. |
+
+## Public Functions
+
+The interface of the Quickstart feature has been kept minimal. It exposes only three functions.
+
+#### `CreateQuickstartHud`
+
+```c
+void CreateQuickstartHud(s16 x, s16 y);
+```
+
+```
+Initializes and places a small HUD element on screen at the specified coordinates.
+Only has an effect when quickstart is enabled.
+
+Parameters
+s16 x: Horizontal position (left edge)
+s16 y: Vertical position (top edge)
+```
+
+#### `QuickstartEmerald` `QuickstartFrlg`
+
+```c
+void QuickstartEmerald(void);
+void QuickstartFrlg(void);
+```
+
+```
+Starts a new game from the title screen when called.
+We have two functions because of the differences in how the two title screens work
+```
+
+## Integration
+
+The aforementioned functions may be of use for integrating this feature into custom title screens. Adding calls to the appropriate function gated with a check should suffice.
+
+```c
+// For the HUD
+if (QUICKSTART && QUICKSTART_HUD)
+  CreateQuickstartHud(x, y);
+```
+
+```
+// To trigger Quickstart
+if (QUICKSTART && JOY_NEW(SELECT_BUTTON))
+    QuickstartEmerald();
+```