From 6b4ebf7629369c10f0348d482be9ba1df93a2038 Mon Sep 17 00:00:00 2001 From: "Zed A. Shaw" Date: Mon, 2 Dec 2024 08:37:52 -0500 Subject: [PATCH] More complete readme but need a screenshot. --- README.md | 90 +++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 77 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index bbfdd45..dcc92aa 100644 --- a/README.md +++ b/README.md @@ -2,15 +2,11 @@ When I was a kid I played a game that used only text characters in a terminal called [Rogue](https://en.wikipedia.org/wiki/Rogue_(video_game). This game ran in my little MSDOS computer using only the ASCII characters the computer supported. No graphics and I think no sound but I can't remember. Despite this very low quality graphical experience the game delivered an amazing game experience. Even today the term "roguelike" denotes certain qualities that come from the original _Rogue_: -* Dying is permanent but each time you restart you'll retain some previous skills or equipment so - the next run is easier. -* However, it's only easier to the point where you previously died, as each level through the - dungeon gets more and more difficult. +* Dying is permanent but each time you restart you'll retain some previous skills or equipment so the next run is easier. +* However, it's only easier to the point where you previously died, as each level through the dungeon gets more and more difficult. * A randomly generated world (dungeon) that features a new experience every time. -* A focus on mechanics rather than graphics, but creative use of the limited graphical characters to - make the game playable. -* This lack of graphics weirdly makes the game _more_ imaginative because you have to fill in what's - going on with your own imagination, similar to a game of Dungeons and Dragons. +* A focus on mechanics rather than graphics, but creative use of the limited graphical characters to make the game playable. +* This lack of graphics weirdly makes the game _more_ imaginative because you have to fill in what's going on with your own imagination, similar to a game of Dungeons and Dragons. This is why I chose Rogue as the basis for my first actual game in C++. @@ -84,18 +80,24 @@ See? That's how Free Speech works. You don't need a LICENSE. ## Build Instructions -Pre-requisites: +On all platforms you'll need these components: -* Meson -- which need Python -* C++ Compiler -- Tested with Clang and G++ -* GNU make -- For the convenience Makefile +* [Meson](https://mesonbuild.com/) -- which needs Python. +* C++ Compiler -- Tested with Clang and G++. You can use my [C++ Setup Guide](https://learncodethehardway.com/courses/learn-cpp-the-hard-way/1-the-basics/01-gearing-up/) which features an automated installer for Windows. +* [GNU make](https://www.gnu.org/software/make/) -- For the convenience Makefile. On Windows you should have this if you used my setup scripts. Otherwise `winget install ezwinports.make` will set you up. +* [git](https://git-scm.com/) -- Which should be on almost every platform, and is installed by default with my Windows setup scripts. -Windows instructions +### Windows Instructions + +I primarily develop in Windows using the above setup, so this should work the best. Open [Windows +Terminal](https://github.com/microsoft/terminal) and run these commands _one at a time_. Don't +copy-past bomb this: ```shell git clone https://git.learnjsthehardway.com/learn-code-the-hard-way/roguish.git cd roguish + # ignore the errors the first time ./scripts/reset_build.ps1 @@ -106,8 +108,70 @@ make make run ``` +After that the game should be running. It'll be in different states depending on how far I've +pushed it, but you should at least have two enemies, some loot that gives you a better torch, and a +room with a light in it. Go find them. + +## Linux and OSX + +Linux and OSX have the same requirements as Windows and almost the same install steps. The only +difference is that once you get your developer tools installed then you only need [Meson](https://mesonbuild.com/). Linux and OSX should have everything else you need or there's a package for it. + +Once you have that installed you can run these commands: + +```shell +git clone https://git.learnjsthehardway.com/learn-code-the-hard-way/roguish.git + +cd roguish + +# ignore the errors the first time +./scripts/reset_build.sh + +# first compile takes a while +make + +./builddir/roguish +``` + +You don't need `make run` because Linux and OSX are sane operating systems that don't lock every +damn thing a process touches. + +### Other Platforms + +No testing done on other platforms but let me know if you get it to build somewhere fun and I'll +mention it. + +## Development Guide + +You can look in the `status.txt` file for my informal TODO list of things to fix and make. I'm not +really accepting contributions from others, but if you want to follow along then that's what I'm +doing. + +If you're just starting out in C++ or programming then the project is designed to be readable by +someone who knows very little. Every file is small and should be easy to read. I don't use any +insane tricks or weird C++ idioms. I also try to avoid too many external libraries so I'll use +plain old [std::vector]() and [std::unordered_map]() rather than external libraries that might be +faster. This is done _on purpose_ so people (myself included) can learn about the basics of C++ and +the STL. + +I also don't do a lot of performance tuning or obsession over _THE CACHE_. Clean, simple, readable +code is more important than squeezing 4% performance out of the code. I do however attempt to +design things so that it doesn't do useless work because the fastest thing you can do in a computer +is nothing. If I can architect away a performance issue and not make the code too complex then I'll +do that instead. + +That means if you have a suggestion for a micro-benchmark improvement that will dramatically boost +performance, but the code is convoluted and hard to understand, then it won't work. If your +suggestion is interesting and provides a massive boost then let me know and I'll check it out. But, +I would also like statistics that show it's better, not just your word. + + +## Known Bugs +* Map Generation isn't refined enough so sometimes it makes a map with no path out. Just start it + again. +Look in `status.txt` for more bugs that aren't as major as this. ## OSX Build Notes