Merge pull request #265 from oskarrough/better-docs

Better docs

Author: oskarrough

DOCUMENTATION.md

@@ -11,15 +11,6 @@ In the root of this project you'll find configuration files as well as three fol
 - [public →](public/) Copied to the web root as-is
 - [tests →](tests/) Contains all tests for the game engine. Nothing for the UI. Run `npm test`.
 
-## Coding style
-
-- JavaScript (ES modules)
-- Web components and Preact HTM for rendering
-- Immer for immutable state updates
-- Error handling: Use try/catch sparingly; prefer validation and early returns
-- JSDoc for documentation
-- No semicolons, single quotes, tabs
-
 ### Game
 
 #### Game State
@@ -82,28 +73,10 @@ Every card must define two exports:
 - default: the card
 - upgrade: upgrade(card) => card
 
-#### dungeon-encounters.js
+#### dungeons.js
 
 Contains different monsters, room and dungeons. All created with methods from the game.
 
-### UI
-
-The UI is made with htm and preact. I've tried not to create too many components and abstractions, although this might come back to haunt us.
-
-Everything starts with [index.html](https://github.com/oskarrough/slaytheweb/blob/main/index.html). When loaded,
-we show a splash/welcome screen as defined in [index.js](https://github.com/oskarrough/slaytheweb/blob/main/src/ui/index.js).
-
-Next, when you tap "Start Game", we load [app.js](https://github.com/oskarrough/slaytheweb/blob/main/src/ui/app.js).
-This one connects everything and manages the game state.
-
-#### Animations
-
-See [animations.js](src/ui/animations.js). Most are made with gsap.
-
-#### Sounds
-
-See [sounds.js](src/ui/sounds.js) using the Web Audio API.
-
 ## Tests
 
 Scripts are checked with [eslint](https://eslint.org/), formatted with [prettier](https://prettier.io/) and tested with [ava](https://github.com/avajs/ava).
@@ -118,10 +91,32 @@ Additionally you can run `npm run lint` to automatically format all scripts acco
 
 You can also just run ava directly and do as you please. Example: `npm test tests/actions.js --watch`
 
+## UI
+
+The UI is made with web components, htm and preact. I've tried not to create too many components and abstractions, and copy/paste more, although this might come back to haunt us.
+
+In order to have easy HTML layouts (and more :tm:), we have Astro set up here. This means you can define new routes in src/ui/pages.
+
+### Animations
+
+See [animations.js](src/ui/animations.js). Most are made with gsap.
+
+### Sounds
+
+See [sounds.js](src/ui/sounds.js) using the Web Audio API.
+
 ## Backend
 
 With the integration of https://github.com/oskarrough/slaytheweb-backend in `game/backend.js`, you can choose to save your current run state in the Slay the Web database. Nothing but game state & date is stored. All runs are visible on `stats.html`.
 
 ## Footnotes
 
 In the beginning I made this diagram of how the game works. It's probably outdated now but keeping it here for reference: https://kinopio.club/slay-the-web-Dh3xUjjHbol7RbCuqZQDn.
+
+- JavaScript (ES modules)
+- Web components and Preact HTM for rendering
+- Immer for immutable state updates
+- Error handling: Use try/catch sparingly; prefer validation and early returns
+- JSDoc for documentation
+- No semicolons, single quotes, tabs
+

src/content/dungeons.js

@@ -0,0 +1,25 @@
+import {Monster} from '../game/monster.js'
+import {MonsterRoom} from '../game/rooms.js'
+import Dungeon from '../game/dungeon.js'
+
+export const createDefaultDungeon = () => {
+	return Dungeon({
+		width: 6,
+		height: 10,
+		minRooms: 3,
+		maxRooms: 4,
+		customPaths: '0235',
+	})
+}
+
+// This is the dungeon used in tests. Don't change it without running tests.
+export const createTestDungeon = () => {
+	const dungeon = Dungeon({width: 1, height: 3})
+	const intents = [{block: 7}, {damage: 10}, {damage: 8}, {}, {damage: 14}]
+	// Add monster rooms on the first three nodes
+	dungeon.graph[1][0].room = MonsterRoom(Monster({hp: 42, intents}))
+	dungeon.graph[2][0].room = MonsterRoom(Monster({hp: 24, intents}), Monster({hp: 13, intents}))
+	dungeon.graph[3][0].room = MonsterRoom(Monster({hp: 42, intents}))
+	return dungeon
+}
+

src/content/dungeon-encounters.js renamed to src/content/monster-rooms.js

@@ -1,37 +1,8 @@
-import Dungeon from '../game/dungeon.js'
-import {MonsterRoom} from '../game/rooms.js'
 import {Monster} from '../game/monster.js'
+import {MonsterRoom} from '../game/rooms.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 efault dungeon currently used.
-export const dungeonWithMap = () => {
-	return Dungeon({
-		width: 6,
-		height: 10,
-		minRooms: 3,
-		maxRooms: 4,
-		customPaths: '0235',
-	})
-}
-
-// 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 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}))
-	dungeon.graph[3][0].room = MonsterRoom(Monster({hp: 42, intents}))
-	return dungeon
-}
-
-// Here are some different monsters we use in the game.
-// should be changed to have monster files, to make adding/editing them easier
+// Groups of monster rooms of varying difficulty. Technically elites and bosses are just stronger monsters.
 export const easyMonsters = {}
 export const monsters = {}
 export const elites = {}
@@ -56,6 +27,7 @@ easyMonsters['Easy does it x2'] = MonsterRoom(
 		random: 1,
 	}),
 )
+
 monsters['RNG does it'] = MonsterRoom(
 	Monster({
 		hp: random(18, 20),
@@ -70,7 +42,6 @@ monsters['Easy one'] = MonsterRoom(
 		random: 2,
 	}),
 )
-
 //not perfect copy of base game monster, but pretty close
 //needs to gain strength (add to the 6 block)
 monsters['jaw worm'] = MonsterRoom(
@@ -108,19 +79,19 @@ monsters['Tiny Trio'] = MonsterRoom(
 	Monster({hp: random(12, 15), random: 2, intents: [{damage: 6}]}),
 	Monster({hp: random(10, 16), random: 3, intents: [{damage: 6}]}),
 )
-elites['monster7'] = MonsterRoom(
-	Monster({
-		hp: 46,
-		intents: [{damage: 12}, {block: 6, damage: 11}, {block: 5, damage: 16}, {}, {block: 6}],
-	}),
-)
 monsters['monster10'] = MonsterRoom(
 	Monster({
 		hp: 28,
 		intents: [{weak: 1}, {block: 10, damage: 10}, {damage: 21}],
 	}),
 )
 
+elites['monster7'] = MonsterRoom(
+	Monster({
+		hp: 46,
+		intents: [{damage: 12}, {block: 6, damage: 11}, {block: 5, damage: 16}, {}, {block: 6}],
+	}),
+)
 elites['monster9'] = MonsterRoom(
 	Monster({
 		hp: 60,

src/game/actions.js

@@ -4,7 +4,7 @@ import {isDungeonCompleted, getRoomTargets, getCurrRoom} from './utils-state.js'
 import powers from './powers.js'
 import {conditionsAreValid} from './conditions.js'
 import {createCard, CardTargets} from './cards.js'
-import {dungeonWithMap} from '../content/dungeon-encounters.js'
+import {createDefaultDungeon} from '../content/dungeons.js'
 
 // Enable support for Map and Set. See https://immerjs.github.io/immer/installation/
 enableMapSet()
@@ -77,13 +77,13 @@ function createNewState() {
 }
 
 /**
- * By default a new game doesn't come with a dungeon. You have to set one explicitly. Look in dungeon-encounters.js for inspiration.
+ * By default a new game doesn't come with a dungeon. You have to set one explicitly. Look in dungeons.js for inspiration.
  * @param {State} state
  * @param {Dungeon} [dungeon]
  * @returns {State} .
  */
 function setDungeon(state, dungeon) {
-	if (!dungeon) dungeon = dungeonWithMap()
+	if (!dungeon) dungeon = createDefaultDungeon()
 	state.dungeon = dungeon
 	return state
 	// return produce(state, (draft) => {

src/game/dungeon.js

@@ -1,5 +1,5 @@
 import {uuid, shuffle, random as randomBetween, pick} from '../utils.js'
-import {easyMonsters, monsters, elites, bosses} from '../content/dungeon-encounters.js'
+import {easyMonsters, monsters, elites, bosses} from '../content/monster-rooms.js'
 import {StartRoom, CampfireRoom} from './rooms.js'
 
 /**

tests/actions.js

@@ -4,7 +4,7 @@ import actions from '../src/game/actions.js'
 import {createCard, CardTargets} from '../src/game/cards.js'
 import {MonsterRoom} from '../src/game/rooms.js'
 import {Monster} from '../src/game/monster.js'
-import {createTestDungeon} from '../src/content/dungeon-encounters.js'
+import {createTestDungeon} from '../src/content/dungeons.js'
 import {getRoomTargets, getCurrRoom, isCurrRoomCompleted} from '../src/game/utils-state.js'
 import {canPlay} from '../src/game/conditions.js'
 

tests/dungeon.js

@@ -1,6 +1,6 @@
 // @ts-ignore
 import test from 'ava'
-import {createTestDungeon} from '../src/content/dungeon-encounters.js'
+import {createTestDungeon} from '../src/content/dungeons.js'
 import actions from '../src/game/actions.js'
 import Dungeon from '../src/game/dungeon.js'
 import {MonsterRoom} from '../src/game/rooms.js'