raycaster/README.md

# The Artisanal Handcrafted Retro-Future "3D" Dungeon Crawler

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.

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.

## STATUS

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.

## Linux Build Notes

Libraries Needed:

* libxi-dev
* libfreetype-dev

It uses c++ so you may need to install a libg++ or libc++ for your system. Usually this is all you
need:

apt install build-essential

## 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?