gered/ack3d
1
0
Fork 0
Code Issues Pull requests Packages Projects Releases Wiki Activity

add a bunch of readme files

Browse source
This commit is contained in:
Gered 2019-11-10 15:51:47 -05:00
parent 35d43cd544
commit ad3e79e811
7 changed files with 429 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

61
README.md Normal file
View file

@ -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).

36
ack_lib/README.md Normal file
View file

@ -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!

37
bpic/README.md Normal file
View file

@ -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.

75
example/README.md Normal file
View file

@ -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!

75
fdemo/README.md Normal file
View file

@ -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!

75
mall/README.md Normal file
View file

@ -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!

70
map_edit/README.md Normal file
View file

@ -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.