add a bunch of readme files
This commit is contained in:
parent
35d43cd544
commit
ad3e79e811
61
README.md
Normal file
61
README.md
Normal 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
36
ack_lib/README.md
Normal 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
37
bpic/README.md
Normal 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
75
example/README.md
Normal file
|
|
@ -0,0 +1,75 @@
|
|||
# Example ACK-3D Application
|
||||
|
||||
|
||||
|
||||
|
||||
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
75
fdemo/README.md
Normal file
|
|
@ -0,0 +1,75 @@
|
|||
# FDEMO
|
||||
|
||||
|
||||
|
||||
|
||||
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
75
mall/README.md
Normal file
|
|
@ -0,0 +1,75 @@
|
|||
# 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
70
map_edit/README.md
Normal file
|
|
@ -0,0 +1,70 @@
|
|||
# DOS Map Editor for ACK-3D
|
||||
|
||||
|
||||
|
||||
|
||||
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.
|
||||
Loading…
Reference in a new issue