feat:docs and annotations

README.md

@@ -14,3 +14,11 @@ Using lazy.nvim:
   opts = {},
 }
 ```
+
+## Configuration
+
+TODO. But right now, nothing to configure. EZPZ.
+
+## Development
+
+Leaning on [Lua Language Server](https://luals.github.io/) for annotations and docs.

TODO.md

@@ -1,5 +1,6 @@
 # TODO
 
+- [ ] docs: use kdheepak/panvimdoc or equivalent
 - [ ] feat(core): add pieces
 - [ ] feat(input): add piece movement
 - [ ] feat(input): add piece rotation
@@ -8,9 +9,9 @@
 - [ ] feat(ui): add pause screen
 - [ ] feat(ui): add score info
 - [ ] feat(ui): add start screen
+- [ ] feat(ui): hide cursor/input/block
 - [ ] feat(ui): namespace for highlights
 - [ ] perf(core): decouple game (loop) tick from level/speed
 - [ ] perf(core): double buffer for rendering
 - [ ] perf(core): should we try virtual text?
 - [ ] test(core): add tests
-- [ ] feat(ui): hide cursor/input/block

doc/tetris.nvim.txt

@@ -0,0 +1,8 @@
+*lazy.nvim.txt*                                   Last change: 2024 January 25
+
+==============================================================================
+Table of Contents                              *tetris.nvim-table-of-contents*
+
+1. tetris.nvim                                       |tetris.nvim-tetris.nvim|
+
+**tetris.nvim** is a pure Lua Tetris game for Neovim.

lua/tetris/init.lua

@@ -1,7 +1,10 @@
 ---local async = require("plenary.async")
+require("tetris.math")
 
 local tetris = {
   input = require("tetris.input"),
+  score_max = 99999999,
+  score_min = 0,
   should_close = false,
   speed = 60,
   ui = require("tetris.ui"),
@@ -64,7 +67,8 @@ tetris.draw_game = function(buffer)
   -- vim.api.nvim_buf_set_lines(buffer, 0, -1, false, lines)
   tetris.ui.draw_layout_main()
 
-  tetris.score = tetris.score + 10
+  -- TODO: ew
+  tetris.score = math.clamp(tetris.score + 10, tetris.score_min, tetris.score_max)
 
   -- TODO: keep positions (row,col) for this in layout, probaly
   vim.api.nvim_buf_set_extmark(tetris.ui.window.buffer, tetris.namespace, 4, 31, {

lua/tetris/input.lua

@@ -1,5 +1,8 @@
+---Input mappings and handlers.
 local input = {}
 
+---Mappings from inputs to actions.
+---@type table
 input.mappings = {
   ["<Esc>"] = "quit",
   ["<LeftMouse>"] = "noop",
@@ -14,9 +17,9 @@ input.mappings = {
   q = "quit",
 }
 
---- Setup bindings for our primary buffer.
---- @param buffer any
---- @param handlers any
+---Setup bindings for our primary buffer.
+---@param buffer any
+---@param handlers any
 input.setup = function(buffer, handlers)
   for key, action in pairs(input.mappings) do
     if action == "noop" then

lua/tetris/layouts.lua

@@ -1,5 +1,11 @@
+---Layouts (views) for the game.
 local layouts = {}
 
+---Convert a string to a table of strings.
+---For drawing to buffers we need a table of strings, where each string
+---is a line. But it's not fun to define layouts as tables.
+---@param layout string
+---@return table
 local string_to_table = function(layout)
   local lines = {}
   for s in layout:gmatch("[^\r\n]+") do
@@ -8,6 +14,8 @@ local string_to_table = function(layout)
   return lines
 end
 
+---Main layout.
+---@return table
 layouts.main = function()
   local layout = [[
 ╭───────────────────────────────────╮

lua/tetris/math.lua

@@ -0,0 +1,13 @@
+--- Math utility functions.
+--- Note that we are snapping these directly to the math library. If you hate it,
+--- open a PR and refactor and do `local tetris_math = require("tetris.math")` or
+--- something and then I will comment about how ugly that is and we can bicker in
+--- public. I will concede and look like a jerk and eventually merge your PR. ;)
+
+---Clamp a number between a minimum and maximum value.
+---@param x number Value to clamp
+---@param min number Minimum value
+---@param max number Maximum value
+function math.clamp(x, min, max)
+  return math.max(math.min(x, max), min)
+end

lua/tetris/ui.lua

@@ -1,37 +1,43 @@
+--- UI module for Tetris.nvim
+
 local layouts = require("tetris.layouts")
 local popup = require("plenary.popup")
-local M = {}
 
-M.window = {
-  buffer = nil,
-  height = 23,
-  id = nil,
-  width = 37,
+--- UI state, mostly.
+local ui = {
+  window = {
+    buffer = nil,
+    height = 23,
+    id = nil,
+    width = 37,
+  },
 }
 
-M.create_window = function()
-  M.window.buffer = vim.api.nvim_create_buf(false, true)
+---Create window and window homies like buffer and
+---setup autocmds to close them when we leave.
+ui.create_window = function()
+  ui.window.buffer = vim.api.nvim_create_buf(false, true)
 
-  local win_id, win = popup.create(M.window.buffer, {
+  local win_id, win = popup.create(ui.window.buffer, {
     border = false,
-    col = math.floor((vim.o.columns - M.window.width) / 2),
+    col = math.floor((vim.o.columns - ui.window.width) / 2),
     highlight = "TetrisWindow",
-    line = math.floor(((vim.o.lines - M.window.height) / 2) - 1),
-    minheight = M.window.height,
-    minwidth = M.window.width,
+    line = math.floor(((vim.o.lines - ui.window.height) / 2) - 1),
+    minheight = ui.window.height,
+    minwidth = ui.window.width,
     noautocmd = true,
   })
 
-  M.window.id = win_id
+  ui.window.id = win_id
 
   vim.api.nvim_create_autocmd("BufLeave", {
-    buffer = M.window.buffer,
+    buffer = ui.window.buffer,
     once = true,
     callback = function()
       pcall(vim.api.nvim_win_close, win_id, true)
       --pcall(vim.api.nvim_win_close, win.border.win_id, true)
       -- TODO: require telescope
-      require("telescope.utils").buf_delete(M.window.buffer)
+      require("telescope.utils").buf_delete(ui.window.buffer)
     end,
   })
 
@@ -40,19 +46,20 @@ M.create_window = function()
   vim.api.nvim_win_set_option(win_id, "winhl", "Cursor:CustomCursor")
 end
 
---- Fill/flood the game window with empty spaces.
--- We cannot write to specific lines/cols in the buffer without there
--- already being text there. So we flood the area to avoid errors.
-M.flood_window = function()
+---Fill/flood the game window with empty spaces.
+---We CANNOT write to specific lines/cols in the buffer without there
+---already being text there. So we flood the area to avoid errors.
+ui.flood_window = function()
   local lines = {}
-  for _ = 1, M.window.height do
-    table.insert(lines, string.rep(" ", M.window.width))
+  for _ = 1, ui.window.height do
+    table.insert(lines, string.rep(" ", ui.window.width))
   end
-  vim.api.nvim_buf_set_lines(M.window.buffer, 0, -1, false, lines)
+  vim.api.nvim_buf_set_lines(ui.window.buffer, 0, -1, false, lines)
 end
 
-M.draw_layout_main = function()
-  vim.api.nvim_buf_set_lines(M.window.buffer, 0, -1, false, layouts.main())
+---Draw our main layout to our main buffer.
+ui.draw_layout_main = function()
+  vim.api.nvim_buf_set_lines(ui.window.buffer, 0, -1, false, layouts.main())
 end
 
-return M
+return ui

stylua.toml

@@ -0,0 +1,6 @@
+column_width = 120
+indent_type = "Spaces"
+indent_width = 2
+
+[sort_requires]
+enabled = true