the-maze/README.md
File Type: text/plain
the-maze
========
Originally a DOS Game written in QBasic, now a FreeBasic in "QB Mode" project. My initial goal was to get it working again and on Linux, without the need for DOS nor actual QBasic. After some manual and code-agent-driven updates in 2026, it's compiling using `-lang fb` and has a revamped, *somewhat* modernized code base, including a more robust `Makefile`. Sound uses QB-style `Play` over SDL2; custom tiles load from editable text `.til` files at runtime.
Building
========
Install FreeBASIC and SDL2 (e.g. `libsdl2-dev` on Debian/Ubuntu). Then type `make` in the code directory. A directory called `out` will be created with the executables and game data... `cd` into it and run `./game`. That's it, there's no install target. (You can also type `make run` in the code dir and it'll build/run everything)
Display options
===============
The game opens a modern `ScreenRes` window with an 80×25 logical text grid (same layout as the original). Defaults: windowed, 2× scale (~1280×800).
./game [options]
--fullscreen, -f Fullscreen --windowed, -w Windowed (default) --scale=N, -s N Pixel scale 1–6 (default 2) --ascii, -a ASCII playfield glyphs (default) --tiles, -t Custom tile graphics from a .til file --tilefile=FILE Tileset file (implies --tiles); default tiles.til --help, -h Show help
Examples: `./game --scale=3`, `./game --tiles`, `make run ARGS='--tilefile=tiles --scale=3'`.
Always run from the `out/` directory (or use `make run`) so `game.ini`, `world1.dat`, and `tiles.til` are found. `make game` / `make run` copy those assets automatically.
`--scale` keeps a fixed 640×400 logical framebuffer (80×25 text cells) and enlarges the window with FreeBASIC's OpenGL 2D mode (`SET_GL_2D_MODE` + `SET_GL_SCALE`) when available.
Playfield collision uses a logical tile map. `--ascii` / `--tiles` only change how those cells are drawn.
`game.ini` holds two lines: the level `.dat` path, then the tileset `.til` path (updated when you change either in-game).
Tile files (`.til`)
===================
Custom graphics are plain text (INI-style), parsed at runtime into 8×16 pixel sprites:
; comments start with semicolon [palette] 0=8 1=yellow
[wall] color=7
++++++
...
- **`[palette]`** — shared accents `0`–`9`, each a CGA index `0`–`15` or name (`yellow`, `light_blue`, …).
- **`[tile_name]`** — one section per sprite (`wall`, `key`, `player_right`, `monster`, …).
- **`color=` / `primary=`** — that tile’s primary CGA colour (used for `#` / `+`).
- **Pixel grid** — up to 16 rows of 8 characters:
- `#` primary colour
- `+` dimmed primary
- `.` black / empty
- `0`–`9` global palette entry
Missing tiles fall back to a simple solid placeholder. Ship/edit `tiles.til` (copied to `out/`).
Keys
====
In the game: Arrow keys move. `E` switches to the level editor. `L` loads a new level file (8 characters or less; default world is `world1.dat` — don't overwrite that lightly). `T` loads a new tileset the same way (enables custom graphics if you were in ASCII mode). `Esc` quits the game.
In the editor: Input is mainly mouse-driven, so you can select object modes at the bottom of the screen and place them with the left button. Erase an object of the current mode using the right mouse button. Use the arrow keys to move rooms. Click `PLAY` to save your world and switch to the game. `Esc` exits to the OS.
Personal Notes
==============
This has been mostly a learning / tinkering exercise and so far I really like building with FreeBasic. Is it going to build the most efficient code? No, but that doesn't really matter for this type of game. What's nice is that you can achieve some C/C++ style structured programming but it's easier to understand due to the BASIC syntax. A perfect fit for smaller, concept-learning projects and games. Also a plus that it can still build DOS binaries.