Merge branch 'main' into feat/text-version

.eslintrc.cjs

@@ -4,12 +4,28 @@ module.exports = {
 		browser: true,
 		es2021: true,
 	},
-	extends: ['eslint:recommended', 'plugin:prettier/recommended'],
+	plugins: ['jsdoc'],
+	extends: [
+		'eslint:recommended',
+		'plugin:prettier/recommended',
+		'plugin:jsdoc/recommended',
+		// 'plugin:jsdoc/recommended-typescript-flavor',
+	],
 	parserOptions: {
 		ecmaVersion: 'latest',
 		sourceType: 'module',
 	},
 	rules: {
 		complexity: ['warn', 14],
+		'jsdoc/require-property-description': 'off',
+		'jsdoc/require-param-description': 'off',
+		'jsdoc/require-returns-description': 'off',
+	},
+	settings: {
+		jsdoc: {
+			tagNamePreference: {
+				property: 'prop',
+			},
+		},
 	},
 }

CHANGELOG.md

@@ -4,8 +4,23 @@ All notable changes to this project will be documented in this file. Dates are d
 
 Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 
+#### [v0.17.1](https://github.com/oskarrough/slaytheweb/compare/v0.17.0...v0.17.1)
+
+- Refactor dungeon and more jsdocs [`#200`](https://github.com/oskarrough/slaytheweb/pull/200)
+- More comments and types [`#199`](https://github.com/oskarrough/slaytheweb/pull/199)
+- Fix save game [`#172`](https://github.com/oskarrough/slaytheweb/pull/172)
+- Document the dungeon & map code better [`#196`](https://github.com/oskarrough/slaytheweb/pull/196)
+- PWA [`#198`](https://github.com/oskarrough/slaytheweb/pull/198)
+- Switch to vite for development [`#195`](https://github.com/oskarrough/slaytheweb/pull/195)
+- Fix action missing card ref [`#193`](https://github.com/oskarrough/slaytheweb/pull/193)
+- Switch to npm for preact+htm [`fa8727e`](https://github.com/oskarrough/slaytheweb/commit/fa8727e8e0761364abf6e087fd949952bce36de5)
+- Replace custom service worker with vite-plugin-pwa [`c11914c`](https://github.com/oskarrough/slaytheweb/commit/c11914c5900d00bb123457e9d1ebd738a6abb803)
+- Update dependencies [`f1b7d22`](https://github.com/oskarrough/slaytheweb/commit/f1b7d22afcb9f85ee75d56e1ce016cae40704978)
+
 #### [v0.17.0](https://github.com/oskarrough/slaytheweb/compare/v0.16.1...v0.17.0)
 
+> 15 July 2023
+
 - Start saving game logs to a central database [`#189`](https://github.com/oskarrough/slaytheweb/pull/189)
 - new card, and added hp/max hp getting functions [`#183`](https://github.com/oskarrough/slaytheweb/pull/183)
 - fixes a few broken links in DOCUMENTATION.md [`#180`](https://github.com/oskarrough/slaytheweb/pull/180)

DOCUMENTATION.md

@@ -60,8 +60,7 @@ On `state.player` we have you, the player. This object describes the health, pow
 
 #### Dungeon
 
-Every game starts in a dungeon. You make your way through rooms to reach the end.
-
+Every game evolves around and in a dungeon. A dungeon consists of a graph (think a 2d array with rows and columns, or positions and nodes, or floors and rooms).
 There are different types of rooms. Like Monster and Campfire. One day there'll be more like Merchant and Treasure or a "random" room.
 
 #### Monsters

jsconfig.json

@@ -1,8 +1,9 @@
 {
 	"compilerOptions": {
-		"checkJs": true,
 		"allowJs": true,
+		"checkJs": true,
 		"target": "esnext",
-		"moduleResolution": "nodenext"
-	},
+		"moduleResolution": "nodenext",
+		"noEmit": true
+	}
 }

package.json

@@ -1,6 +1,6 @@
 {
   "name": "slaytheweb",
-  "version": "0.17.0",
+  "version": "0.17.1",
   "license": "AGPL-3.0-or-later",
   "homepage": "https://slaytheweb.cards",
   "repository": "https://github.com/oskarrough/slaytheweb",
@@ -23,6 +23,7 @@
     "docco": "^0.9.1",
     "eslint": "^8.45.0",
     "eslint-config-prettier": "^8.8.0",
+    "eslint-plugin-jsdoc": "^46.4.4",
     "eslint-plugin-prettier": "^5.0.0",
     "prettier": "3.0.0",
     "release-it": "^16.1.3",

src/content/dungeon-encounters.js

@@ -1,10 +1,14 @@
 import Dungeon from '../game/dungeon.js'
-import {MonsterRoom, Monster} from '../game/dungeon-rooms.js'
-import {random} from '../game/utils.js'
+import {MonsterRoom} from '../game/rooms.js'
+import {Monster} from '../game/monster.js'
+import {random} from '../utils.js'
+
+// A dungeon encounter is the combination of a Room and Monster(s).
 
 // Hello. With the imported functions above you can create a dungeon with different rooms and monsters.
 // Should be able to support even more monsters (4-5)
-// This is the dungeon currently used.
+
+// This is the efault dungeon currently used.
 export const dungeonWithMap = () => {
 	return Dungeon({
 		width: 6,
@@ -18,7 +22,7 @@ export const dungeonWithMap = () => {
 // This is the dungeon used in tests. Don't change it without running tests.
 export const createTestDungeon = () => {
 	const dungeon = Dungeon({width: 1, height: 3})
-	// The tests rely on the first room having a single monster, second two monsters.
+	// The tests rely on the first room having a single monster, second room two monsters.
 	const intents = [{block: 7}, {damage: 10}, {damage: 8}, {}, {damage: 14}]
 	dungeon.graph[1][0].room = MonsterRoom(Monster({hp: 42, intents}))
 	dungeon.graph[2][0].room = MonsterRoom(Monster({hp: 24, intents}), Monster({hp: 13, intents}))

src/game/action-manager.js

@@ -1,22 +1,34 @@
-import Queue from './queue.js'
 import actions from './actions.js'
+import Queue from '../utils.js'
+
+/** @typedef {import('./actions.js').State} State */
 
 /**
- * @typedef {Object} FutureAction
+ * @typedef {object} FutureAction
  * @prop {string} type - the name of a function in actions.js
  * @prop {any} [any] - arguments are passed to the action
  */
 
 /**
- * @typedef {Object} PastAction
+ * @typedef {object} PastAction
  * @prop {string} type - the name of a function in actions.js
- * @prop {import('./actions.js').State} state
+ * @prop {State} state
+ */
+
+/**
+ * @typedef {object} ActionManager
+ * @prop {function(FutureAction):void} enqueue
+ * @prop {function(State):State} dequeue
+ * @prop {function():PastAction} undo
+ * @prop {Queue} future
+ * @prop {Queue} past
  */
 
 /**
  * The action manager makes use of queues to keep track of future and past actions in the game state + undo.
- * @param {Object} props
- * @prop {boolean} props.debug - whether to log actions to the console
+ * @param {object} props
+ * @param {boolean} props.debug - whether to log actions to the console
+ * @returns {ActionManager} action manager
  */
 export default function ActionManager(props) {
 	const future = new Queue()
@@ -34,8 +46,8 @@ export default function ActionManager(props) {
 	/**
 	 * Deqeueing runs the oldest action (from the `future` queue) on the state.
 	 * The action is then moved to the `past` queue.
-	 * @param {import('./actions.js').State} state
-	 * @returns {import('./actions.js').State} new state
+	 * @param {State} state
+	 * @returns {State} new state
 	 */
 	function dequeue(state) {
 		// Get the oldest action