From 55feff23fb17205e55498804aa333e260168e885 Mon Sep 17 00:00:00 2001 From: "Zed A. Shaw" Date: Sun, 16 Feb 2025 02:59:40 -0500 Subject: [PATCH] Make the README better so people can try to build it. --- README.md | 141 +++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 130 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index e82cf11..f9edf4e 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,134 @@ -# Simple Raycaster Study +# The Artisinal Handcrafted Retro-Future "3D" Dungeon Crawler -This is a study project for me to learn the raycasting technique. It's an older technique that's -not really used much but I'm learning game dev historically and it's definitely been used in the -past (Doom). +Welcome to my latest obsession, and turn based dungeon crawler in the style of old school raycasted +games like _Wizardry_, _Might and Magic_, _Ultima_, and similar games. The game uses SFML 3.x as +it's "cross platform layer" but other than that everything is hand coded by me. It's fully +artisinal, created manually, with nothing but a terminal and vim. No LSPs, AI, or anything. -## Don't Study This Code +This code is truly a work of art. Like an espresso at that Speakeasy Coffee bar in Brooklyn nobody +talks about. You know the one? You don't? Oh sorry, I thought you were cool. -This code is mostly a tech study and demo, not an actual game. It _could_ be a game but it will -require a significant cleanup to improve the layout and design. It's also the culmination of -studying about 6 different tutorials on raycasting so it has a weird mix-match code style as I -brought ideas over from other tutorials. +## STATUS -Eventually this will be more understandable, but for now just browse it casually and ignore the -inconsistent style and kind of stupid structure. +Currently it's only officially tested on Windows, but I'm not really using anything OS specific (I +think). + +## Where's the LICENSE? + +You don't need a LICENSE that gives everything away to thieving corporations just to publish your +works online. Nobody makes artists, musicians, painters, photographers, or sculptors get a license +before posting online, so why do programmers need one? You worried you'll get sued? Ok, so just put +a disclaimer but why do you _also_ have to give your hard work away for anyone to steal and profit +from just so they don't sue you? + +You don't, and no matter what the OSI says, nobody can sue you if they steal your code and cause a +plane to crash. _They_ would get sued for stealing your code and putting it in a plane, not you. +Requiring _only_ programmers to release their code with a license to avoid lawsuits creates a +[Chilling Effect](https://www.thefire.org/research-learn/chilling-effect-overview) on programmer free speech and that violates the First Amendment. + +So this code isn't licensed, it's copyright by default. I'm publishing it using my free speech +rights to express myself and that means you can look at it the same as if I posted a painting or an +essay on my blog. I obviously can't sue you for just looking at it and playing the game because I +published it so you can, but _that doesn't mean you own it._ You can't resell it, fork it, +nothing. + +Just grab the code and play it. That's it. Tell people about it. Fair use says you can even record +videos reviewing it and talking about it. + +See? That's how Free Speech works. You don't need a LICENSE. + +## Build Instructions + +On all platforms you'll need these components: + +* [Meson](https://mesonbuild.com/) -- which needs Python. +* C++ Compiler -- Tested with Clang and G++. You can use my [Windows C++ Setup Guide](https://git.learnjsthehardway.com/learn-code-the-hard-way/lcthw-windows-installers) 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 + +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/raycaster.git + +cd raycaster + +# ignore the errors the first time +./scripts/reset_build.ps1 + +# first compile takes a while +make + +# this copies the binary so you can run it +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 a few enemies, some loot, and rooms 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/raycaster.git + +cd raycaster + +# ignore the errors the first time +./scripts/reset_build.sh + +# first compile takes a while +make + +./builddir/raycaster +``` + +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 `notes.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 + +It's early so probably a bunch of bugs. + +## OSX Build Notes + +* Quite a bad experience. Need to install Python, cmake, meson, and ninja all which are in homebrew but if you don't use homebrew then this is a problem. +* You need to run the .command script in Application/your python that updates the SSL certs. +* You have to give iTerm access to your keystrokes...because wtf it already has them?