Repository files navigation

Prior releases have been buggy. That turned out to an interaction between Doom 64 and some low-level CPU cache management code in KOS. I will hesitate to call it a bug as we don't knowwhy the change that fixes it, actually fixes it (yet).

The copy of KOS bundled with this repo has the change for this cache issue. Doom 64 for Dreamcast is now stable, so stable we have been unable to reproduce any of the previous hangs for about a month now.

WARNING 1: If you have built Doom 64 from this repo prior to February 16 2025 @ 05:00 UTC, you will need to unpack/rebuilddoom64_kos.tgz as well as doing amake clean andmake to regenerate the game data files.

WARNING 2: If you have built Doom 64 from this repo prior to February 15 2025 @ 05:00 UTC, you will need to regenerate the WADs fromdoom64.z64 as the generated files have changed.

WARNING 3: If you have played with VMU saving prior to January 16 2025, you need to erase any existingdoom64stg file ("D64 settings / Doom 64 settings data"). This can be done from the BIOS VMU manager or from the Doom 64 VMU manager (hold START button on legal screen) prior to starting your next game. There are new breaking changes to support future extensibility.

Please pay close attention to the README as significant new features have been added and the build instructions have changed.

• Enemy, projectile and sector movement interpolation. Everything moves nicely and smoothly when the frame rate is above 30 FPS.

• CUSTOMIZABLE CONTROLLER MAPPINGS. See build instructions for details on how this works.

• UNCAPPED FRAME RATE, variable with correct physics. 60 FPS in the majority of the game with lights and normal mapping.

• 8bpp world textures. Increased performance when filtering is disabled. Reduces VRAM pressure / frequency of texture flushing (reduced frequency of graphical glitches in bonus levels).

• VMU SAVING IS NOW SUPPORTED.5 free blocks are required.

Note: There must be a controller in the first controller port, and the VMU must be inserted into the first slot of the first controller.

Both settings and game passwords can be saved. Setting changes are saved automatically when you exit any settings related menu. If you notice a short pause when moving between menus, the settings file is being updated.

Game progress saving happens in the intermission screen between levels. Hit a button when the password is shown and you will be prompted to save. Loading game progress can be done at any time from the 'Password' menu. I have only been able to test this with OEM Sega VMU. It is known that Performance 4x Memory Pack does NOT work.

I have also implemented the original Controller Pak Management menus. Be careful, you can nuke your other saved games if you select the wrong one. Press Y+A together to select a file for deletion.

• Rumble/Vibration/Purupuru Pack is also now supported. Go toOptions,Movement, and selectRumble: StrikerDC. Only the built-in feedback of RetroFighters StrikerDC wireless controller is supported currently. You may experience crashes or lack of feedback from other devices.

• Keyboard and mouse are also supported. I don't have much to comment on that, I got this from a pull request.

• Custom Knee Deep In The Dead content with Dreamcast-exclusive enhancements. Maps by z0k (with mods by Mittens). Music by Andrew Hulshult.

Commercial redistribution of this additional content is not allowed. It is against the terms of use.

But because some of you are literal children and need it spelled out explicitly, any redistribution of this project with game data is copyright infringement and prohibited by law.

• The entire world and the all of the player's weapons have real-time normal mapping (DOT3 bump mapping, with tangent-space light direction vectors and three-dimensional normal texture maps,that normal mapping) that interacts with my custom dynamic lighting system (up to 16 simultaneous point sources, geometry tessellation for improved quality) (bUt WaIt, DoT3 BuMp MaPpInG oN tHe DrEaMcAsT iS iMpoSsIbLe?!?! because...)

VRAM captures, running on Dreamcast hardware

Lots of work went into this and I hope you all enjoy it.

Youwill have to do a tiny bit of actual work to get this going. If you don't have 30 to 45 minutes to spare, just go play on Steam and call it a day. The results are worth it though.

Pre-requisites

Whatever the directory you cloned this github repo to is named and wherever it is located, it will be referred to in this document as

doom64-dc

This guide will assume that you cloned it into your home directory.

If you need to get to the top level of the repo, it will say

cd ~/doom64-dc

The build is known to work on the following platforms as of the current commit:

Debian (version?)Ubuntu 22.04Windows 11 - Cygwin 64-bitWindows (version?) - DreamSDK

It should work on most other Linux environments.

You will need a host/native GCC install and a full working Dreamcast/KallistiOS compiler toolchain install.

See [https://dreamcast.wiki/Getting_Started_with_Dreamcast_development] for instructions.

A modified version of KOS is provided as part of the Doom 64 repo. This is the only version that will guarantee a working game. Please do not file github issues if you are not using it. They will be closed with prejudice.

These instructions assume it is the only version of KOS on your system. If you already have KOS installed, please move it elsewhere before you begin.

To set it up, after building/installing compilers, open a terminal and do the following (please pay attention to the# part):

cd ~/doom64-dctar xzf doom64_kos.tgz# WARNING: YOU NEED TO REPLACE any existing kos directory, please move it to a safe place first if KOS already exists# i.e.  mv /opt/toolchains/dc/kos ~/BACKUP_OF_MY_OLD_KOScd ./doom64_koscp -r kos /opt/toolchains/dc/cd ..rm -rf ./doom64_kosexit

Once you have the unpacked kos directory in place, open a new terminal.

Source the providedenviron.sh file and build KOS as follows:

cd /opt/toolchains/dc/kossource ./environ.shmakeexit

Now you have a version of KOS identical to the version I use for development.

How to generate Doom 64 disc image

N64 retail game support

Somehow acquire a Doom 64 ROM in Z64 format and name itdoom64.z64 .

Check that your Doom 64 ROM is the correct one.

The below is the expected md5sum output.

md5sum doom64.z64b67748b64a2cc7efd2f3ad4504561e0e doom64.z64

Now place a copy ofdoom64.z64 in thewadtool directory.

Nightdive Lost Levels support

Buy the Nightdive Studios edition of Doom 64 (the 2020 PC release) from Steam or wherever.

Check that your Doom 64 IWAD is the correct one.

The below are two possible md5sum outputs that will lead the the correct N64 format maps being generated.

md5sum DOOM64.WAD654c57d19f5c4a52cf8c63e34caa2fd2 DOOM64.WAD

or

md5sum DOOM64.WAD0aaba212339c72250f8a53a0a2b6189e DOOM64.WAD

Now place a copy of the Doom 64 IWAD from the installation directory in thewadtool directory,renamed to all lowercasedoom64.wad.

Compiling Doom 64 for Dreamcast

Go to the repo directory and compile it like any other KallistiOS project. Make sure you source your KOS environment first.

To build the source into an ELF file, runmake.

source /opt/toolchains/dc/kos/environ.shcd ~/doom64-dcmake cleanmake

As part of the build,Make will automatically build and runwadtool.

This should take a minute or less to run depending on your processor and disk speed.

The first terminal output you see should match the following except for the time values and a note aboutretail orretail + nightdive (the first time you runmake):

Script dir is: ~/doom64-dc/wadtoolCompiling wadtoolRunning wadtoolreal   0m20.368suser   0m19.836ssys    0m0.233sGenerated data files in specified selfboot directory: ~/doom64-dc/wadtool/../selfbootDone.

Subsequent runs will not rebuildwadtool but start atRunning wadtool or skip that too if the generated files already exist inselfboot.

When it is complete, you will now have the following new files in the~/doom64-dc/selfboot directory:

alt.wadpow2.wadtex/non_enemy.texmaps/map01.wadmaps/...maps/map33.wad

If you provided a Nightdive Doom 64 IWAD you will also have the following additional files in~/doom64-dc/selfboot:

maps/map34.wadmaps/...maps/map40.wad

You now have all of the updated files required to run Doom 64 for Dreamcast in the places they need to be.

Custom controller mappings

You can now provide a customized controller mapping.

Before you make your disc image, create a file in~/doom64-dc/selfboot namedcontrols.ini.

Note that Dreamcast START is still mapped to N64 START (pause, exit menus, etc).

The format is simple.

Each line consists of the game action, the number of Dreamcast buttons mapped to itand the actual buttons to map to the action, if any. Values are separated by commas (,).If you add any spaces, the mapping file will fail to parse. Sorry. It was this or nothing.

Valid game actions are one of:RIGHT,LEFT,UP,DOWN,ATTACK,USE,AUTOMAP,SPEED,STRAFE,STRAFELEFT,STRAFERIGHT,WEAPONBACKWARD,WEAPONFORWARD.

Each action must start on its own line, and they must be present in the file in the order listed above.

The valid number of mapped buttons for each action is0,1 or2.

If 0 buttons are mapped, the line ends at0.

If 1 button is mapped, a single button should be present, separated with a comma from the1.

If 2 buttons are mapped, two buttons should be present, separated with commas from the2 and each other. Their ordering does not matter.

Valid Dreamcast buttons are one of:DPAD_RIGHT,DPAD_LEFT,DPAD_UP,DPAD_DOWN,BUTTON_A,BUTTON_B,BUTTON_X,BUTTON_Y,TRIGGER_L,TRIGGER_R.

If nocontrols.ini file is provided, the game defaults to the original hard-coded button mapping. Here is a working example of acontrols.ini file for reference (it also happens to be the default control mapping):

RIGHT,1,DPAD_RIGHTLEFT,1,DPAD_LEFTUP,1,DPAD_UPDOWN,1,DPAD_DOWNATTACK,1,BUTTON_AUSE,1,BUTTON_BAUTOMAP,2,BUTTON_X,BUTTON_YSPEED,0STRAFE,0STRAFELEFT,1,TRIGGER_LSTRAFERIGHT,1,TRIGGER_RWEAPONBACKWARD,1,BUTTON_XWEAPONFORWARD,1,BUTTON_Y

Creating a disc image

Once you have built (or downloaded)doom64.elf it is time to make a playable disc image from it.

If you havemkdcdisc installed and reachable from yourPATH, you can use thecdi build target to create a self-booting CDI.

cd ~/doom64-dcmake cdi

This will produce an output filedoom64.cdi in~/doom64-dc.

If you havemkisofs installed and reachable from yourPATH, you can use thedsiso build target to create an ISO suitable for loading from SD card or hard drive with Dreamshell ISO loader.

cd ~/doom64-dcmake dsiso

This will produce an output filedoom64.iso in~/doom64-dc.

Alternative instructions for disc image generation on Windows

If you are on Windows and unable to buildmkdcdisc, there is another way to make a self-booting CDI.

Grab the latest patchedBootDreams from:https://github.com/TItanGuy99/BootDreams/releases

Follow the previous instructions located earlier in this document to generate an ELF file.

Next, from aCygwin/Mingw/DreamSDK terminal, go to the repo directory and generate1ST_READ.BIN from the ELF:

cd ~/doom64-dcsh-elf-objcopy.exe -O binary build/doom64.elf build/doom64.bin/opt/toolchains/dc/kos/utils/scramble/scramble.exe build/doom64.bin selfboot/1ST_READ.BIN

StartBootDreams and make sure it is on theDiscJuggler setting.

CheckISO settings (under theExtras menu).

Make sure to selectFull Filenames,Joliet andRock Ridge.

Now return to the mainBootDreams window.

Click theBrowse button next to theSelfboot folder section.

Find your~/doom64-dc/selfboot folder in the Windows Folder selection dialog. Single-click on it to select/highlight it and click OK.

Change theCD label if you feel like it.

You can leaveDisc format on the default setting.

Click theProcess button.

ClickYes when prompted if you want to create a DiscJuggler image.

If you get Error dialog aboutmissing IP.BIN, clickYes to create one.

When the file dialog pops up, pick a location for your CDI file, change the name if you'd like and clickSave.

Once theCDI4DC window disappears and you get theCreated successfully dialog, clickOK.

You're ready to go and can burn the image to CD or process it further.

If you are trying to use any other tool or operating system to make an image, you are on your own.

Good luck. :-)

Notes on GDEMU usage

I do not own a GDEMU so I cannot vouch for the correctness of the following section.

I was informed that some extra configuration is required to run the CDI from GDEMU. I was told the following settings added toGDEMU.INIwill get Doom 64 to run. (edited because I am getting conflicting information)

image_tests = 0

Immorpher [https://github.com/Immorpher] for introducing me to the entire Doom 64 RE scene, getting me hooked on hacking the N64 version. His role as Subject Matter Expert was invaluable, helping me see (and hear) all of the inaccuracies and bugs I missed along the way.

This port is heavily based off of his Merciless Edition and Doom 64 XE work [https://github.com/Immorpher/doom64xe]

which in turn would not be possible without the excellent work on reverse engineering Doom 64 by Erick194, found here [https://github.com/Erick194/DOOM64-RE]

Everyone on the KOS team and the Simulant Discord but especially

Falco Girgis [https://github.com/gyrovorbis] and Paul Cercueil [https://github.com/pcercuei] for their tireless work on fixing and extending the KOS PowerVR code and answeringNON-STOP questions about "IS THIS SUPPOSED TO WORK AND WHAT STUPID DID I DO TO MAKE IT NOT WORK"

Luke Benstead [https://github.com/kazade] for the excellent glDC project, where I learned what near-z clipping is and how to implement it. Completely lost without that.

"Lobotomy" for creating some really nice normal maps and helping me learn how to do the rest

"erik5249" for developing a BC5 compression scheme for normal maps that helped me achieve my goal of keeping all (compressed) textures cached in RAM; also, providing a reference compressor and very performant decompressor

Andy Barajas [https://github.com/andressbarajas] for help debugging my filesystem use around my normal map implementation, and his libwav for streaming ADPCM music (bundled in the repo)

Ruslan Rostovtsev [https://github.com/DC-SWAT] for pointing me toward streaming ADPCM instead of using ADX for soundtrack and his excellent KOS PRs for fixing the streaming audio performance.

Piers Holdaway [https://github.com/Mittens0407] for doing performance modifications on the Knee Deep In The Dead/z0k content.

"StrikerTheHedgefox" [https://github.com/StrikerTheHedgefox] for starting with testing and moving on to many new additions to the project (motion interpolation, vmu stats).

Everyone who helped test builds along the way and offered endless moral support, thanks.

iD Software and Midway (🪦) for my favorite Doom game of all time.