From 4dafc84ca02ae4054746349e72bb1d1b018c34c8 Mon Sep 17 00:00:00 2001 From: Aaron Taylor Date: Wed, 1 Apr 2020 02:01:35 -0700 Subject: [PATCH] Wrote README.md for Hunt the Wumpus. --- examples/hunt-the-wumpus/README.md | 158 ++++++++++++++++++++++++++++ examples/hunt-the-wumpus/README.txt | 83 --------------- 2 files changed, 158 insertions(+), 83 deletions(-) create mode 100644 examples/hunt-the-wumpus/README.md delete mode 100644 examples/hunt-the-wumpus/README.txt diff --git a/examples/hunt-the-wumpus/README.md b/examples/hunt-the-wumpus/README.md new file mode 100644 index 0000000..0b6a9ac --- /dev/null +++ b/examples/hunt-the-wumpus/README.md @@ -0,0 +1,158 @@ +# Overview # + +Hunt the Wumpus is a text game where the player navigates a cave, avoiding +bottomless pits and super bats, all while shooting arrows at a Wumpus. To play, +type `make run`. + +For those unfamiliar with the history of Hunt the Wumpus, Wikipedia has a nice +article describing gameplay, development and history. + + + + +# Configuration # + +If you want to tweak game settings like the number of rooms, arrows or +obstacles, the file `wump_conf.pvvs` contains all the user-configurable +settings. After editing the file, simply run `make clean run` to experience +the new settings. + + +# Instructions # + +The Wumpus typically lives in a cave of twenty rooms, with each room having +three tunnels connecting it to other rooms in the cavern. Caves may vary, +however, depending on options specified when starting the game. + +The game has the following hazards for intrepid adventurers to wind their +way through: + + Pits -- If you fall into one of the bottomless pits, you find yourself + slung back out on the far side of the Earth and in very poor + shape to continue your quest since you're dead. + + Bats -- As with any other cave, the Wumpus cave has bats in residence. + These are a bit more potent, however, and if you stumble into + one of their rooms they will rush up and carry you elsewhere in + the cave. + + Wumpus -- If you happen to walk into the room the Wumpus is in you'll find + that he has quite an appetite for young adventurous humans! Not + recommended. + +The Wumpus, by the way, is not bothered by the hazards since he has sucker +feet and is too big for a bat to lift. If you try to shoot him and miss, +there's also a chance that he'll up and move himself into another cave, +though by nature the Wumpus is a sedentary creature. + +Each turn you may either move or shoot a crooked arrow. Moving is done +simply by specifying 'm' for move and the number of the room that you'd +like to move down a tunnel towards. Shooting is done similarly; indicate +that you'd like to shoot one of your magic arrows with an 's' for shoot, +then list a set of connected room numbers through which the deadly shaft +should fly! + +If your path for the arrow is incorrect, however, it will flail about in +the room it can't understand and randomly pick a tunnel to continue +through. You might just end up shooting yourself in the foot if you're +not careful! On the other hand, if you shoot the Wumpus you've WON! + + +# Example # + + vvhitespace/examples/hunt-the-wumpus % make clean run + + Welcome to Hunt the Wumpus! + + Please press 16 keys to seed the RNG. + | + ................ + + Instructions? (y/n) + n + + You're in a cave with 20 rooms and 3 tunnels leading from each room. + There are 2 bats and 2 pits scattered throughout the cave, and your + quiver holds 5 custom super anti-evil Wumpus arrows. Good luck. + + ---------- + + You are in room 14 of the cave and have 5 arrows remaining. + *sniff* (You smell the evil Wumpus nearby!) + This room contains tunnels to the following rooms: 18 11 17 + Move or shoot? (m/s) + m + To which room do you wish to move? + 17 + + ---------- + + You are in room 17 of the cave and have 5 arrows remaining. + *sniff* (You smell the evil Wumpus nearby!) + This room contains tunnels to the following rooms: 4 14 0 + Move or shoot? (m/s) + m + To which room do you wish to move? + 4 + + ---------- + + You are in room 4 of the cave and have 5 arrows remaining. + *sniff* (You smell the evil Wumpus nearby!) + This room contains tunnels to the following rooms: 17 1 7 + Move or shoot? (m/s) + m + To which room do you wish to move? + 17 + + ---------- + + You are in room 17 of the cave and have 5 arrows remaining. + *sniff* (You smell the evil Wumpus nearby!) + This room contains tunnels to the following rooms: 4 14 0 + Move or shoot? (m/s) + s + Through which rooms do you wish to shoot your arrow? + (type 5 room numbers separated by spaces) + 14 18 1 + The arrow sails out of room 17 and enters room 14. + The arrow sails out of room 14 and enters room 18. + The arrow sails out of room 18 and enters room 1. + + *thwock!* *groan* *crash* + A horrible roar fills the cave, and you realize, with a smile, that you + have slain the evil Wumpus and won the game! You don't want to tarry for + long, however, because not only is the Wumpus famous, but the stench of + dead Wumpus is also quite well known, a stench plenty enough to slay the + mightiest adventurer at a single whiff!! + + +# Heap Assignments # + +Game data is stored starting at heap address `0x1000`. A variety of settings +are located here, one per word. + + GAME_DATA = 0x1000 + + GAME_DATA+0 = Number of rooms in cave + GAME_DATA+1 = Number of rooms containing pits + GAME_DATA+2 = Number of rooms containing bats + GAME_DATA+3 = Number of tunnels per room + GAME_DATA+4 = Maximum arrow flight distance + GAME_DATA+5 = Number of arrows + GAME_DATA+6 = Player location + GAME_DATA+7 = Wumpus location + +Room data is stored as an array of structs starting at heap address `0x2000`. +Each room struct has the following layout. + + BASE+0 = bool:contains_pit? (valid options are 0 or 1) + BASE+1 = bool:contains_bat? (valid options are 0 or 1) + BASE+2 = int:connected room (-1 indicates no tunnel, >0 is index of destination room) + ... + BASE+n = int:connected room + +Each struct is `number_of_tunnels_per_room + 2` words in size. Room numbers +begin at `0` and can be used as indices into this room data array. + +The heap space from `0x3000` and up is used as a user input buffer. diff --git a/examples/hunt-the-wumpus/README.txt b/examples/hunt-the-wumpus/README.txt deleted file mode 100644 index c001660..0000000 --- a/examples/hunt-the-wumpus/README.txt +++ /dev/null @@ -1,83 +0,0 @@ -TODO LIST: - - - Update README - - Write functions for moving wumpus, player movement, player shooting, parsing player commands. - - Write a function 'get highest tunnel index' for use in the 'check for pits/bats/wumpus' functions. - - Double-check per-file TODOs for critical tasks. - - Double-check #includes for all subroutines. - - Re-order subroutines in all files for readability. - -================================================================================ - -# Subroutine Labels # - -NSSVTTTTTTTTSSSSSSSSN | Mark: 11111111 00000000 (wump_kill) -NSSVTTTTTTTTSSSSSSSTN | Mark: 11111111 00000001 (kill_wump) -NSSVTTTTTTTTSSSSSSTSN | Mark: 11111111 00000010 (no_arrows) -NSSVTTTTTTTTSSSSSSTTN | Mark: 11111111 00000011 (shoot_self) -NSSVTTTTTTTTSSSSSTSSN | Mark: 11111111 00000100 (jump) -NSSVTTTTTTTTSSSSSTSTN | Mark: 11111111 00000101 (pit_kill) -NSSVTTTTTTTTSSSSSTTSN | Mark: 11111111 00000110 (pit_survive) -NSSVTTTTTTTTSSSSSTTTN | Mark: 11111111 00000111 (please_seed_rng) -NSSVTTTTTTTTSSSSTSSSN | Mark: 11111111 00001000 (problem_with_yes_no_answer) -NSSVTTTTTTTTSSSSTSSTN | Mark: 11111111 00001001 (instructions) -NSSVTTTTTTTTSSSSTSTSN | Mark: 11111111 00001010 (cave_description) - -NSSVTSSSSSSSN | MARK: 10000000 (wump) -NSSVTSSSSSSTN | MARK: 10000001 (set_config_values) -NSSVTSSSSSTSN | MARK: 10000010 (wump_init) -NSSVTSSSSSTTN | MARK: 10000011 (seed_rng) -NSSVTSSSSTSSN | MARK: 10000100 (build_cave) -NSSVTSSSSTSTN | MARK: 10000101 (populate_cave) -NSSVTSSSSTTSN | MARK: 10000110 (clear_cave_data) -NSSVTSSSSTTTN | MARK: 10000111 (generate_cave_hop_length) -NSSVTSSSTSSSN | MARK: 10001000 (get_tunnel_destination) -NSSVTSSSTSSTN | MARK: 10001001 (set_tunnel_destination) -NSSVTSSSTSTSN | MARK: 10001010 (get_random_room) -NSSVTSSSTSTTN | MARK: 10001011 (get_room_struct_size) -NSSVTSSSTTSSN | MARK: 10001100 (room_has_bats) -NSSVTSSSTTSTN | MARK: 10001101 (room_has_pits) -NSSVTSSSTTTSN | MARK: 10001110 (build_circular_tunnels) -NSSVTSSTSSSSN | MARK: 10010000 (set_bats) -NSSVTSSTSSSTN | MARK: 10010001 (set_pits) -NSSVTSSTSSTSN | MARK: 10010010 (reset_cave_population) -NSSVTSSTSSTTN | MARK: 10010011 (populate_bats) -NSSVTSSTSTSSN | MARK: 10010100 (populate_pits) -NSSVTSSTSTSTN | MARK: 10010101 (place_player) -NSSVTSSTSTTSN | MARK: 10010110 (build_random_tunnels) -NSSVTSSTSTTTN | MARK: 10010111 (get_next_tunnel_slot) -NSSVTSSTTSSSN | MARK: 10011000 (get_answer) -!!!NSSVTSSTTSSTN | MARK: 10011001 (get_line) -NSSVTSSTTSTSN | MARK: 10011010 (wump_loop) -NSSVTSSTTSTTN | MARK: 10011011 (print_cave_description) -NSSVTSSTTTSSN | MARK: 10011100 (are_bats_near) -NSSVTSSTTTSTN | MARK: 10011101 (are_pits_near) -NSSVTSSTTTTSN | MARK: 10011110 (is_wumpus_near) -NSSVTSSTTTTTN | MARK: 10011111 (is_wumpus_very_near) -NSSVTSTSSSSSN | MARK: 10100000 (room_has_wumpus) -NSSVTSTSSSSTN | MARK: 10100001 (print_room_stats) - -================================================================================ - -# Heap Assignments # - -GAME_DATA_BASE = 0x1000 - -GAME_DATA_BASE = Number of rooms in cave -GAME_DATA_BASE+001 = Number of pits -GAME_DATA_BASE+002 = Number of bats -GAME_DATA_BASE+003 = Number of links per room -GAME_DATA_BASE+004 = Maximum arrow flight distance -GAME_DATA_BASE+005 = Number of arrows -GAME_DATA_BASE+006 = Player location -GAME_DATA_BASE+007 = Wumpus location - -ROOM_DATA_BASE = 0x2000 - Each room is structured as: - BASE+0 = bool:contains_pit? (valid options are 0 or 1) - BASE+1 = bool:contains_bat? (valid options are 0 or 1) - BASE+2 = int:connected room (-1 indicates no tunnel, 0 or greater is the index of the destination room) - ... - BASE+n = int:connected room (last: see 'links per room') - -USER_INPUT_BUFFER = 0x3000 -- 2.20.1