diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f5a3dc4
--- /dev/null
+++ b/README.md
@@ -0,0 +1,61 @@
+# ACK-3D for DOS/Watcom
+
+This repository contains fixed up code and demo projects/assets for the ACK-3D engine that 
+was included in the book, "Amazing 3-D Games Adventure Set" by Lary Myers, published in 1995.
+
+The CD included with that book contained multiple versions of the ACK-3D engine, two of which were
+for DOS (one for Watcom C++ 9.5 and the other Borland C++ 4.0/4.5) and another copy for Windows
+which was also the latest version of the ACK-3D engine at that time. The two DOS versions do not
+build out of the box without issues (crash bugs, etc). Additionally, the code for the DOS version
+of the map editor does not build as-is.
+
+In this repository, I have taken the Windows version included on the book's CD and back-ported it
+to DOS using Watcom C++ 10.0a. I have also fixed build issues with the DOS map editor and cleaned
+up the makefiles and build scripts for all included tools and projects. Lary used his own custom
+`MK.EXE` tool which kind of did stuff similar to a makefile, but it was his own custom tool that
+was limited. I have not really left Windows compatibility as that was not a goal of mine. Having
+said that, I don't think it would be super difficult to add that back if someone desired it.
+
+Some minor bugs and other improvements have been made, but nothing major. Many of the existing bugs
+that were present in ACK-3D remain (e.g. secret doors render strangely or not at all in many cases,
+and multi-height walls still can be seen through ceilings, etc.). I may try to fix some of these
+things in the future.
+
+Finally, I have included a somewhat simpler example project that has been thoroughly commented.
+This project I hope serves to demonstrate what Lary covered in chapter's 11 and 14 of the book,
+but instead focused on DOS only and without going overboard with extra things like the FDEMO
+and MALL projects both did.
+
+Also, I wrote two posts about this whole adventure [here](http://blarg.ca/amazing-3-d-games-adventure-set/) 
+and [here](http://blarg.ca/rebuilding-ack-3d-for-dos/) if anyone is interested.
+
+## Repository Layout
+
+### `/ack_lib`
+
+The core ACK-3D library, based on the Windows version included on the book's CD.
+
+### `/bpic`
+
+Source for the `BPIC` utility discussed in the book in Appendix A, used for constructing
+resource files.
+
+### `/map_edit`
+
+Source and data files for the DOS version of the map editor. Unlike the Windows version
+"ACKEDIT" (not included in this repository), this does not work with resource files directly and
+so is not _quite_ as convenient to work with.
+
+### `/fdemo`
+
+Source and assets for the "FDEMO" project discussed briefly in the book in Appendix C.
+
+### `/mall`
+
+Source and assets for the "MALL" project also discussed briefly in the book in Appendix C. This
+project is very, very similar to the "FDEMO" project and really only differs by assets used.
+
+### `/example`
+
+An example project I created from scratch (but using assets from the Station Escape, FDEMO and
+MALL projects from the book's CD).
diff --git a/ack_lib/README.md b/ack_lib/README.md
new file mode 100644
index 0000000..c808afb
--- /dev/null
+++ b/ack_lib/README.md
@@ -0,0 +1,36 @@
+# ACK-3D Library
+
+Source code for the latest version of the ACK-3D library (at least, at the time of publishing of
+Lary Myer's book, "Amazing 3-D Games Adventure Set" in 1995) back-ported to DOS. Windows
+compatibility has not been kept. A Watcom `makefile` has been added, replacing a build script for
+Lary's custom `MK.EXE` build tool.
+
+## Requirements
+
+To build, you will need Watcom C++ and Borland TASM. I used Watcom C++ 10.0a and Borland TASM 4.0,
+but you should be able to build with newer versions (maybe even _slightly_ older versions too).
+
+## Building
+
+Within this directory, run
+
+```
+> wmake
+```
+
+This will build using the included `makefile` using a debug build settings.
+
+To build using a release configuration:
+
+```
+> wmake target_config=release
+```
+
+In either case, you should get an output artifact `ACKLIB.LIB` on successful build.
+
+### Compiler Settings Note
+
+Of particular note is that `/zp1` is specified for both debug and release builds. This matches
+Lary's original build scripts but is also a requirement as some things in the code make 
+assumptions that might not hold true for larger alignment settings (e.g. `/zp4`). Change this
+at your own risk!
diff --git a/bpic/README.md b/bpic/README.md
new file mode 100644
index 0000000..7755682
--- /dev/null
+++ b/bpic/README.md
@@ -0,0 +1,37 @@
+# BPIC
+
+Source code for the `BPIC` utility, which is a resource file builder/compiler for the ACK-3D
+engine. A Watcom `makefile` has been added, replacing a build script for Lary's custom `MK.EXE` 
+tool.
+
+This can be used to build the `pics.dtf`-type resource files used by all the demo/example projects.
+All the details regarding ACK-3D resource files can be found in Appendix A of the book.
+
+Unlike the version that shipped on the book's CD, this version has been updated so that it does
+not assume that files are located in the current working directory. Instead, files specified by
+the input `.DAT` file are assumed to be located beside that file, making it possible to do things
+like place `BPIC.EXE` somewhere on your PATH instead of needing to copy it around to all of your
+project asset directories.
+
+## Requirements
+
+To build you will need Watcom C++. I used Watcom C++ 10.0a, but you should be able to build with 
+a newer version (maybe even a _slightly_ older version too).
+
+## Building
+
+Within this directory, run
+
+```
+> wmake
+```
+
+This will build using the included `makefile` using a debug build settings.
+
+To build using a release configuration:
+
+```
+> wmake target_config=release
+```
+
+In either case, you should get an output artifact `BPIC.EXE` on successful build.
\ No newline at end of file
diff --git a/example/README.md b/example/README.md
new file mode 100644
index 0000000..b9f5108
--- /dev/null
+++ b/example/README.md
@@ -0,0 +1,75 @@
+# Example ACK-3D Application
+
+![EXAMPLE1](https://github.com/gered/ack3d/raw/master/scrnshot/example1.gif "EXAMPLE1")
+![EXAMPLE2](https://github.com/gered/ack3d/raw/master/scrnshot/example2.gif "EXAMPLE2")
+
+Source files and assets for a simple example project utilizing the ACK-3D engine. Uses art assets
+found on the CD included with the book "Amazing 3-D Games Adventure Set" by Lary Myers, published 
+in 1995.
+
+The purpose of this project is to provide a very simple application that helps illustrate things
+discussed in detail in chapters 11 and 14 of the book. Chapter 14 in particular goes through the
+process of creating an ACK-3D application from scratch, but it is Windows-specific. This project
+aims to be somewhat of a DOS-equivalent of the project presented in that chapter.
+
+## Requirements
+
+To build you will need Watcom C++. I used Watcom C++ 10.0a, but you should be able to build with
+a newer version (maybe even a _slightly_ older version too).
+
+You must build `ACKLIB.LIB` prior to building this project. Please check the `/ack_lib` directory
+at the root of this repository first.
+
+## Building
+
+Within this directory, run
+
+```
+> wmake
+```
+
+This will build using the included `makefile` using a debug build settings.
+
+To build using a release configuration:
+
+```
+> wmake target_config=release
+```
+
+In either case, you should get an output artifact `EXAMPLE.EXE` on successful build.
+
+## Editing the Map
+
+You must build the DOS map editor. Please check the `/map_edit` directory at the root of this 
+repository first.
+
+Once you have a working DOS map editor, run:
+
+```
+> \path\to\mapedit.exe \path\to\example\assets\example.med
+```
+
+To try out your map alterations you will need to rebuild the `pics.dtf` resource file.
+
+To add/remove bitmaps you will need to edit the `example.med` file for the map editor. However,
+you **ALSO** need to modify the `example.dat` and `example.inf` files to successfully rebuild the
+`pics.dtf` resource file. See Appendix A and the last section of Chapter 15 in the book for more
+information on ACK-3D resource files and using the DOS map editor. Please make sure you are well
+familiar with these chapters, as getting all these files exactly right can be quite tricky!
+
+## Rebuilding `pics.dtf`
+
+You must build the `BPIC` tool. Please check the `/bpic` directory at the root of this repository
+first.
+
+If you wish to make changes to the assets used by this project (bitmaps and/or map), make whatever
+changes you like to the `example.dat` file (which just lists the files to be included in the 
+resource file) and `example.inf` file. Then to build a new `pics.dtf` run:
+
+```
+> \path\to\bpic.exe \path\to\example\assets\example.dat \path\to\example\pics.dtf
+```
+
+See Appendix A and the last section of Chapter 15 in the book for more information on ACK-3D 
+resource files and using the DOS map editor. Please make sure you are well familiar with these 
+chapters, as getting all these files exactly right can be quite tricky!
diff --git a/fdemo/README.md b/fdemo/README.md
new file mode 100644
index 0000000..412f0b0
--- /dev/null
+++ b/fdemo/README.md
@@ -0,0 +1,75 @@
+# FDEMO
+
+![FDEMO1](https://github.com/gered/ack3d/raw/master/scrnshot/fdemo1.gif "FDEMO1")
+![FDEMO2](https://github.com/gered/ack3d/raw/master/scrnshot/fdemo2.gif "FDEMO2")
+
+Source code and assets for the FDEMO project contained on the CD that was included on the book
+"Amazing 3-D Games Adventure Set" by Lary Myers, published in 1995. The source code has been
+fixed up a little bit. A Watcom `makefile` has been added, replacing a build script for Lary's 
+custom `MK.EXE` build tool.
+
+## Requirements
+
+To build you will need Watcom C++ and Borland TASM. I used Watcom C++ 10.0a and Borland TASM 4.0,
+but you should be able to build with newer versions (maybe even _slightly_ older versions too).
+
+You must build `ACKLIB.LIB` prior to building this project. Please check the `/ack_lib` directory
+at the root of this repository first.
+
+To hear the background music you will need a Sound Blaster compatible sound card. This project is
+hard coded to use address 220h, IRQ 5, DMA 1. However you can adjust these settings in the
+`StartBGmusic` function found in `fdemo.c`.
+
+## Building
+
+Within this directory, run
+
+```
+> wmake
+```
+
+This will build using the included `makefile` using a debug build settings.
+
+To build using a release configuration:
+
+```
+> wmake target_config=release
+```
+
+In either case, you should get an output artifact `FDEMO.EXE` on successful build.
+
+## Editing the Map
+
+You must build the DOS map editor. Please check the `/map_edit` directory at the root of this 
+repository first.
+
+Once you have a working DOS map editor, run:
+
+```
+> \path\to\mapedit.exe \path\to\fdemo\assets\fdemo.l01
+```
+
+To try out your map alterations you will need to rebuild the `pics.dtf` resource file.
+
+To add/remove bitmaps you will need to edit the `fdemo.l01` file for the map editor. However,
+you **ALSO** need to modify the `fdemo.dat` and `fdemo.inf` files to successfully rebuild the
+`pics.dtf` resource file. See Appendix A and the last section of Chapter 15 in the book for more
+information on ACK-3D resource files and using the DOS map editor. Please make sure you are well
+familiar with these chapters, as getting all these files exactly right can be quite tricky!
+
+## Rebuilding `pics.dtf`
+
+You must build the `BPIC` tool. Please check the `/bpic` directory at the root of this repository
+first.
+
+If you wish to make changes to the assets used by this project (bitmaps and/or map), make whatever
+changes you like to the `fdemo.dat` file (which just lists the files to be included in the 
+resource file) and `fdemo.inf` file. Then to build a new `pics.dtf` run:
+
+```
+> \path\to\bpic.exe \path\to\fdemo\assets\fdemo.dat \path\to\fdemo\pics.dtf
+```
+
+See Appendix A and the last section of Chapter 15 in the book for more information on ACK-3D 
+resource files and using the DOS map editor. Please make sure you are well familiar with these 
+chapters, as getting all these files exactly right can be quite tricky!
diff --git a/mall/README.md b/mall/README.md
new file mode 100644
index 0000000..7131b71
--- /dev/null
+++ b/mall/README.md
@@ -0,0 +1,75 @@
+# MALL
+
+![MALL](https://github.com/gered/ack3d/raw/master/scrnshot/mall.gif "MALL")
+
+Source code and assets for the MALL project contained on the CD that was included on the book
+"Amazing 3-D Games Adventure Set" by Lary Myers, published in 1995. The source code has been
+fixed up a little bit. A Watcom `makefile` has been added, replacing a build script for Lary's 
+custom `MK.EXE` build tool.
+
+## Requirements
+
+To build you will need Watcom C++ and Borland TASM. I used Watcom C++ 10.0a and Borland TASM 4.0,
+but you should be able to build with newer versions (maybe even _slightly_ older versions too).
+
+You must build `ACKLIB.LIB` prior to building this project. Please check the `/ack_lib` directory
+at the root of this repository first.
+
+To hear the background music you will need a Sound Blaster compatible sound card. This project 
+attempts to read a config file `ack3d.cfg` to load sound card configuration, but such a file is 
+not included in this repository. Either add this file or adjust the default settings found in 
+`mall.c` within the `ReadConfigFile` function. But default, address 220h, IRQ 5, DMA 1 is used.
+
+## Building
+
+Within this directory, run
+
+```
+> wmake
+```
+
+This will build using the included `makefile` using a debug build settings.
+
+To build using a release configuration:
+
+```
+> wmake target_config=release
+```
+
+In either case, you should get an output artifact `MALL.EXE` on successful build.
+
+## Editing the Map
+
+You must build the DOS map editor. Please check the `/map_edit` directory at the root of this 
+repository first.
+
+Once you have a working DOS map editor, run:
+
+```
+> \path\to\mapedit.exe \path\to\mall\assets\mall.l01
+```
+
+To try out your map alterations you will need to rebuild the `pics.dtf` resource file.
+
+To add/remove bitmaps you will need to edit the `mall.l01` file for the map editor. However,
+you **ALSO** need to modify the `mall.dat` and `mall.inf` files to successfully rebuild the
+`pics.dtf` resource file. See Appendix A and the last section of Chapter 15 in the book for more
+information on ACK-3D resource files and using the DOS map editor. Please make sure you are well
+familiar with these chapters, as getting all these files exactly right can be quite tricky!
+
+## Rebuilding `pics.dtf`
+
+You must build the `BPIC` tool. Please check the `/bpic` directory at the root of this repository
+first.
+
+If you wish to make changes to the assets used by this project (bitmaps and/or map), make whatever
+changes you like to the `mall.dat` file (which just lists the files to be included in the 
+resource file) and `mall.inf` file. Then to build a new `pics.dtf` run:
+
+```
+> \path\to\bpic.exe \path\to\mall\assets\mall.dat \path\to\mall\pics.dtf
+```
+
+See Appendix A and the last section of Chapter 15 in the book for more information on ACK-3D 
+resource files and using the DOS map editor. Please make sure you are well familiar with these 
+chapters, as getting all these files exactly right can be quite tricky!
diff --git a/map_edit/README.md b/map_edit/README.md
new file mode 100644
index 0000000..54431b3
--- /dev/null
+++ b/map_edit/README.md
@@ -0,0 +1,70 @@
+# DOS Map Editor for ACK-3D
+
+![MAPEDIT1](https://github.com/gered/ack3d/raw/master/scrnshot/mapedit1.gif "MAPEDIT1")
+![MAPEDIT2](https://github.com/gered/ack3d/raw/master/scrnshot/mapedit2.gif "MAPEDIT2")
+
+Source code and assets for the DOS map editor contained on the CD that was included on the book
+"Amazing 3-D Games Adventure Set" by Lary Myers, published in 1995. The source code has been
+fixed up a little bit and sources/assets for a second, older version of this map editor have been
+removed. A Watcom `makefile` has been added, replacing a build script for Lary's custom `MK.EXE` 
+build tool.
+
+Unlike the version that shipped on the book's CD, this version has been updated so that it does
+not assume that files are all located in the current working directory. Instead the following is
+what happens for path handling:
+
+* The `medit.dtf` file required by the map editor is assumed to be located in the same directory as `MAPEDIT.EXE`
+* Files specified by the map editor description file are assumed to be located in the same directory as that description file.
+
+These changes make it possible to do things like place `MAPEDIT.EXE` and `MEDIT.DTF` somewhere on
+your PATH instead of needing to copy them around to all of your project asset directories.
+
+## Requirements
+
+To build you will need Watcom C++ and Borland TASM. I used Watcom C++ 10.0a and Borland TASM 4.0,
+but you should be able to build with newer versions (maybe even _slightly_ older versions too).
+
+You must build `ACKLIB.LIB` prior to building this project. Please check the `/ack_lib` directory
+at the root of this repository first.
+
+Because the DOS map editor requires it's own `medit.dtf` resource file, you must also build the
+`BPIC.EXE` tool prior to building this project, as the included `makefile` will attempt to build
+this resource file as part of a normal build. Please check the `/bpic` directory at the root of
+this repository first.
+
+## Building
+
+Within this directory, run
+
+```
+> wmake
+```
+
+This will build using the included `makefile` using a debug build settings.
+
+To build using a release configuration:
+
+```
+> wmake target_config=release
+```
+
+In either case, you should get an output artifact `MAPEDIT.EXE` on successful build.
+
+## How to Run
+
+To run the map editor, you must provide it with a text map description file or "configuration file"
+as it is referred to in the book. This file specifies what `.MAP` file to load, in addition to
+what bitmaps to load, what objects are available for placement and a bunch of other things. These
+are very similar to the `.INF` files used by ACK-3D resource files (e.g. `pics.dtf`) but do **NOT**
+confuse the two! They are not the same thing!
+
+This map editor does **NOT** read ACK-3D resource files like `pics.dtf`. It is only capable of
+producing `.MAP` files that are to be included in resource files. This is very much unlike the 
+Windows version of the map editor that was included on the book's CD (which is not included in this
+repository).
+
+Please read the last section of Chapter 15 in the book for more information on using the DOS map
+editor and what needs to go in configuration files. Unfortunately, the book's description of
+configuration files is very light (only a single page), so you will also want to refer to the
+`/fdemo/assets/fdemo.l01`, `/mall/assets/mall.l01` and `/example/assets/example.med` configuration 
+files found in this repository as examples to help you write your own.