diff --git a/README.md b/README.md index c874c93c..c24e9e45 100644 --- a/README.md +++ b/README.md @@ -2,25 +2,91 @@ ![Docs](https://github.com/ucsd-cse125-sp24/group3/actions/workflows/docs.yml/badge.svg) -TODO: Game description here, with screenshots. +Wrath of Zeus is a 3v1 asymmetric maze escape game where 3 players attempt to escape a maze while Zeus tries to stop them from above, and it was all developed through the course +of 10 weeks as a project for UCSD's CSE 125 course. + +The players have to find a magical orb and escape within a time limit, while Zeus can use lightning bolts, dim the lights, and place various traps in order to stop them. + +The players win when one player escapes with the orb. However, picking up the orb for the first time starts a 5 minute timer. If after 5 minutes the players have not escaped +the maze, then Zeus wins. In addition, Zeus can prematurely start the timer before the players pick up the orb if the players die 3 times. + +An important thing to keep in mind while playing is that the color of the torchlights is your guide through the maze. If you see the torches start to turn more blue, then +you are getting closer to the orb, and if they start to turn more white, then you are getting closer to the exit. This is crucial for both the players and Zeus as they +navigate around the maze and try to find their way out / smite those pesky mortals. + +## Screenshots + +## Important Notes Before Playing + +### General + +1. By default the game will load in configuration options from the file titled "Config" or "Config.json" +2. If your client or server fails to open with no explanation, it is likely that you have a malformed config file. For an error message you can try running the program in the command line. If you are unsure how to do that, then I would recommend you revert your config file back to the default. +3. The UI is optimized to work on 1920x1080p monitors. On any other resolution it will attempt to scale UI, but it will likely look very off. +4. The networking code will likely be unplayable on anything other than a LAN, and even on Wi-Fi it will be suboptimal. +5. You can increase the number of players in a lobby, but certain elements of the UI may break and we cannot make any promises about performance! Anecdotally, however, the game + still plays well with 5 total players. + +### Config Options Explanations + +{ + "port"------------------> port that the server runs on and the client connects to + "server": { + "lobby_name"--------> name of the server lobby + "lobby_broadcast"---> whether or not the server sends discovery packets on the LAN + "max_players"-------> how many players must connect to the server before the game can start + "disable_zeus"------> whether or not a player should be allowed to play as Zeus + "skip_intro"--------> whether or not the intro cutscene should be skipped + "disable_enemies"---> whether or not enemies should spawn in the maze + "maze": { + "directory"-----> high level directory that all of the maps are in + "procedural"----> whether or not to use a procedurally generated maze + "maze_file"-----> filepath (relative to the above directory) of a maze file to load in, if procedural is false + } + }, + "client": { + "lobby_discovery"---> whether or not the client listens for servers that are broadcasting discovery packets + "fullscreen"--------> whether or not the window should be fullscreen, or a 1920x1080p window + "fps_counter"-------> whether or not to display the current FPS in the top left of the screen + "presentation"------> shifts the hotbar UI up slightly, for use during the CSE 125 demo to make sure the UI could be seen by audience members in the auditorium + "render": 80--------> beyond this distance, for players no objects will be rendered, and for Zeus certain traps will not be rendered + } +} + +### Custom Map Generation + +If you would like to try your hand at creating some custom mazes or rooms which will be used in the procedural generation algorithm, you can create appropriate maze +files in the "maps" directory. If you just want to load in an entirely custom maze then it doesn't matter where it is placed (as long as you put the appropriate path +in your configuration file), but if you want the procedural algorithm to use your rooms then you should place them in the directories called "10x10" and "20x20". +There is also a directory called "40x40" and the game will attempt to use these 40x40 rooms in the game, but I cannot promise that they will totally work as they are very much untested as we found it was too much effort to make engaging 40x40 rooms and you did not gain much from it. But maybe you will have better luck with it! + +Rules When Designing Rooms: +1. A room must be fully connected, which means that entering from any entryway you should be able to exit from any other entryway in that room. +2. Room door placements must be along the midpoints of the 10x10 sections of each room, as shown in the .empty template maze files. +3. You CAN block entryways into a room, but for 20x20 and 40x40 rooms if you block off one entryway you must also block off all of the other entryways on that side. +4. I think the game will let you make a room with no entrances, but you shouldn't do that for obvious reasons. ## Attributions TomMusic's [Free Fantasy 200 SFX Pack](https://tommusic.itch.io/free-fantasy-200-sfx-pack). -## Documentation +## Development + +All of the following sections are aimed towards development + +### Code Documentation View deployed documentation [here](https://cse125.ucsd.edu/2024/cse125g3/docs/html/) -### Build Docs Locally +#### Build Docs Locally 1. We are using Doxygen which you can install locally from [here](https://www.doxygen.nl/download.html) 2. Run `doxygen` from the root of the directory 3. Open the `html` files in the `docs` directory of the repo -## Setup +### Setup -### Windows (In Visual Studio) +#### Windows (In Visual Studio) 1. Download Visual Studio (if you are on a lab computer, it will already be installed) 2. Clone the repo @@ -30,7 +96,7 @@ View deployed documentation [here](https://cse125.ucsd.edu/2024/cse125g3/docs/ht - `git clone https://github.com/ucsd-cse125-sp24/group3.git` 3. Everything should just work�. To run the program, you can click on the green arrow at the top bar that says "Select Startup Item." There is a dropdown arrow on the right side which will let you select between running the client and the server. -### Linux / Mac +#### Linux / Mac Note: If you work locally this way, you should make sure that before you merge anything into main that it also compiles on a lab computer running Visual Studio. There might be some small differences between how the microsoft compiler handles things, and how `g++` handles things, and we always want to make sure it compiles on a lab computer. @@ -75,34 +141,6 @@ Note: If you work locally this way, you should make sure that before you merge a - `bin/server` (to run the server) - Note that the full filepaths for the executables are `build/bin/server` and `build/bin/client`, so if you are outside of the build directory you will need to give the full path. -### Windows (Without Visual Studio) - -I'm keeping this more for legacy reasons since this doesn't work on the lab computers, but if you want to use windows but don't want to use the Visual Studio IDE, then this is one way you can get it to work. - -This also has the same caveat as above, in that before merging anything in you should verify it compiles on a lab computer running Visual Studio. - -This also is relatively janky. On my Desktop computer, for some reason if you try and compile a C++ program using g++ from Powershell it works fine, but if you try and do it from Git Bash it seg faults (even in a simple Hello World program). - -1. Download Dependencies - 1. `cmake` - - Minimum version 3.13 - - [Install Instructions](https://cgold.readthedocs.io/en/latest/first-step/installation.html) - 2. `g++` - - Follow [this](https://www.freecodecamp.org/news/how-to-install-c-and-cpp-compiler-on-windows/) tutorial. - 3. `make` - - Inside of the `msys2 MINGW64` terminal (the above tutorial should have had you install it), enter `pacman -S make`. - - Then, go back to your environment variable settings and add `C:\msys64\usr\bin` to your system path. - - (This is at `View Advanced System Settings` > `Environment Variables` > Double Click on System Path at the bottom) - - Make sure that in powershell if you type in `make` it recognizes the command. That is how you know it is installed correctly. - 4. OpenGL - - TODO: decide on version - - TODO: link install instructions here -2. Follow the same steps as the Linux / Mac instructions. You may need to add some extra information when you run `CMake`. - - Instead of running `cmake ..`, you might have to run `cmake -G "Unix Makefiles" ..` - -I would generally recommend using Visual Studio if you are working on Windows, since it seems to just work, but I was also able to get this working. - -## Development ### Code Structure @@ -141,18 +179,16 @@ For example, if you want to add a file somewhere in the shared library section o Depending on where you need to link the library (client, server, shared), you will need to go to that `CMakeLists.txt` file and include the relevant CMake incantations/spells/general wizardry to link that library into the specific target. This will likely vary depending on what you are trying to add. -## Useful VSCode Extensions +### Useful VSCode Extensions - [C++ Intellisense](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools) - [General Productivity](https://marketplace.visualstudio.com/items?itemName=jirkavrba.subway-surfers) -## Models +### Models You can download models from our Google Drive folder [here](https://drive.google.com/drive/folders/1N7a5cDgMcXbPO0RtgznnEo-1XUfdMScM?usp=sharing) and place them in `src/client/models`. Alternatively, you can install [gdown](https://github.com/wkentaro/gdown) and run `make pull_models` to automatically pull them. - - -## Testing +### Testing We are using [GoogleTest](https://google.github.io/googletest/) for unit testing. They run automatically in GitHub actions or can also be done manually. @@ -188,11 +224,11 @@ TEST(FactorialTest, HandlesPositiveInput) { ``` 3. Run the tests locally with the steps above or with GitHub actions -## Linting +### Linting We are using [cppcheck](https://github.com/danmar/cppcheck) for linting and static code analysis. They run automatically with GitHub actions. -### Suppressing errors +#### Suppressing errors You can suppress a single error by adding comments in the following format after the lint in question: @@ -202,15 +238,15 @@ int x = 5; // cppcheck-suppress unusedVariable You can also pass in `--suppress ` to cppcheck. You can modify the flags that `make lint` uses by modifying the lint target's definition in the root level CMakeLists.txt. -### Linting locally +#### Linting locally -#### Linux/macOS +##### Linux/macOS Install cppcheck on your system based on instructions [here](https://cppcheck.sourceforge.io/) -#### Windows +##### Windows Visual Studio supports a [cppcheck plugin](https://github.com/VioletGiraffe/cppcheck-vs-addin/tree/1.5) -#### Run +### Run From inside the build directory run: