NeoQuest

A Neovim plugin that turns your editor into a progressive RPG-style learning game.

Practice real Neovim skills inside real buffers, in your real environment, with your real plugins. Every mission is a real-world coding scenario. Every chapter builds on the last.

No sandboxing. No fake editor. The whole game runs inside your Neovim.

---

Requirements

• Neovim >= 0.9.0
• Git (for Chapter 11 missions)
• Optional: any combination of the following plugins — missions adapt to what you have:
  • gitsigns.nvim, vim-fugitive, or lazygit.nvim (Chapter 11)
  • telescope.nvim, nvim-tree, harpoon, leap.nvim, oil.nvim, mini.surround, comment.nvim (Chapter 09)
  • Any LSP server configured via nvim-lspconfig or Mason (Chapter 10)

---

Installation

lazy.nvim

{
  "your-username/neoquest.nvim",
  config = function()
    require("neoquest").setup()
  end,
}

packer.nvim

use {
  "your-username/neoquest.nvim",
  config = function()
    require("neoquest").setup()
  end,
}

vim-plug

Plug 'your-username/neoquest.nvim'

Then in your init.lua:

require("neoquest").setup()

---

Quick Start

:NeoQuest

This opens the dashboard on first run and resumes your current mission on subsequent runs.

To jump straight into the action:

:NeoQuest start

---

Commands

Command	Action
:NeoQuest	Open the dashboard
:NeoQuest start	Resume current mission
:NeoQuest chapter {n}	Jump to a specific chapter (1–12)
:NeoQuest hint	Reveal the next hint level (−10 XP)
:NeoQuest skip	Skip the current mission (no XP awarded)
:NeoQuest stats	Open the stats screen
:NeoQuest dashboard	Open the full dashboard
:NeoQuest scan	Re-run the environment detector
:NeoQuest reset	Wipe all progress and start over

In-mission keymaps (working buffer only)

Key	Action
<leader>?	Reveal next hint
<leader>nq	Skip this mission

---

Chapters

#	Title	Theme
01	Survival Mode	You just SSH'd into a prod server. Vim is the only editor. Survive.
02	Motion Mastery	Move fast without touching the mouse.
03	Editing Fundamentals	Refactor a config file under time pressure.
04	Text Objects	Edit a JSON API response without retyping structure.
05	Search & Replace	You inherited a legacy codebase. Rename everything.
06	Registers	Multi-clipboard like a professional.
07	Macros	50 repetitive edits in a CSV. Do it in under 5 keystrokes.
08	Windows & Buffers	Juggling 4 files during a debugging session.
09	Your Plugins	Personalized missions based on your installed plugins.
10	LSP Workflows	Navigate and refactor using the Language Server Protocol.
11	Git Integration	A full feature branch workflow without leaving Neovim.
12	Master Missions	Real-world compound scenarios requiring the full skill tree.

Chapters 09, 10, and 11 are dynamic — they scan your environment and generate missions based on what you have installed.

---

XP & Leveling

Level	Title	XP Required
1	Novice	0
2	Apprentice	500
3	Journeyman	1,500
4	Craftsman	4,000
5	Expert	10,000
6	Vimmaster	25,000
7	Legend	60,000

XP is awarded per mission based on hints used and whether you beat par keystrokes. Progress never goes backward — every attempt earns something.

---

Progress Storage

Progress is saved to ~/.local/share/nvim/neoquest/progress.json. It is human-readable and portable. No cloud sync — everything stays local.

---

How It Works

NeoQuest scans your Neovim configuration at startup:

• Detects your plugin manager (lazy, packer, vim-plug) and installed plugins
• Reads active LSP servers
• Detects your <leader> key
• Finds your plugin keymaps (e.g. what key opens Telescope)

All hints and mission descriptions use your actual keybindings, not generic placeholders.

---

License

MIT