JFDuke3D Documentation
Index
System Requirements
At minimum, you need:
- 64-bit Intel, AMD, or compatible CPU
- OpenGL 2.1 capable GPU
- (Windows) Vista or newer (7, 8, 10)
- (Mac) macOS 10.9 (Mavericks) or newer
Additionally, these platforms and architectures are supported when building from source code:
- 32-bit Intel/AMD, and 32 or 64-bit ARM CPUs
- OpenGL ES 2.0 capable GPUs, e.g.
- Broadcom VideoCore IV (tested with Raspberry Pi 3 B+)
- ARM Mali-T860 (tested with Libre Computer ROC-RK3399-PC)
Source code can be found in this Git repository along with build instructions.
Installation and Setup
After unzipping the JFDuke3D package somewhere on your computer, run the main executable: JFDuke3D.app
on macOS, duke3d.exe
on Windows. You ought to see the startup window open at the Game tab.
You will now need to import the game data from a commercial release or the shareware version of Duke Nukem 3D as the game will not work without it.
- Click the "Choose a location..." button, then navigate to a location where Duke Nukem 3D data can be found.
- Choose a folder and JFDuke3D will then scan the location you've selected, copying any compatible game data it finds.
Where game data files are stored by JFDuke3D depends on the operating system you are using:
- (Linux, shared with all users)
/usr/local/share/games/jfduke3d
- (Linux, single user)
~/.jfduke3d
- (macOS, single user)
~/Library/Application Support/JFDuke3D
- (Windows) wherever you've put duke3d.exe
Below are known locations of Duke Nukem 3D game data for various sources:
- MS DOS Registered version CD-ROM
- In the
DN3DINST
directory of the disc. - MS DOS Atomic Edition CD-ROM
- In the
ATOMINST
directory of the disc. - Megaton Edition from Steam on macOS
- In Steam, go to Duke Nukem 3D: Megaton Edition, open the 'gear' menu, choose Manage > Browse local files. Make note of this location to use for importing.
- Megaton Edition from Steam on Windows
- In Steam, go to Duke Nukem 3D: Megaton Edition, open the 'gear' menu, choose Manage > Browse local files. Make note of this location to use for importing.
- Atomic Edition from GOG.com on macOS
- In GOG Galaxy 2, go to Duke Nukem 3D Atomic Edition, open the 'options' menu (beside Play), choose Manage installation > Show folder. Make note of this location to use for importing.
- Atomic Edition from GOG.com on Windows
- In GOG Galaxy 2, go to Duke Nukem 3D Atomic Edition, open the 'options' menu (beside Play), choose Manage installation > Show folder. Make note of this location to use for importing.
- 20th Anniversary World Tour from Steam on Windows
- In Steam, go to Duke Nukem 3D: 20th Anniversary, open the 'gear' menu, choose Manage > Browse local files. Make note of this location to use for importing.
- MS DOS Shareware version
If you have a downloaded an original 3D Realms distribution file named
3DDUKE13.ZIP
:- Unzip
3DDUKE13.ZIP
to obtain theDN3DSW13.SHR
file. - Rename
DN3DSW13.SHR
file toDN3DSW13.ZIP
, then unzip it.
- Unzip
"Portable" Installation
Typically the game will store its configuration information and saved games in a private location for your user account:
- (Linux)
~/.jfduke3d
- (macOS)
~/Library/Application Support/JFDuke3D
- (Windows)
C:\Users\your-name\AppData\JFDuke3D
To have the game instead store these files in the working directory where the game was started, create an empty file named user_profiles_disabled
(no extension) beside the executable. You can put the duke3d.grp
file in the same location, thus making everything self-contained and 'portable'.
Music
Music playback with JFDuke3D has some extra features that may be of interest.
FluidSynth MIDI (Linux, BSD)
JFDuke3D supports the software MIDI synthesiser FluidSynth if it is available at compile time. Two challenges typically affect getting FluidSynth to output music. The first is providing a SoundFont for the synthesiser to use, and the second is setting the correct audio device for FluidSynth to output its audio.
Starting with the SoundFont: if when you start JFDuke3D no music is playing, and you see messages like so in the terminal after exiting, then you will need to provide a SoundFont.
Checking music inits.
MUSIC_Init: trying FluidSynth
FluidSynthDrv: using version 2.1.7, built with 2.1.7
fluidsynth: error: Unable to open file "/usr/share/soundfonts/default.sf2"
fluidsynth: error: Couldn't load soundfont file
fluidsynth: error: Failed to load SoundFont "/usr/share/soundfonts/default.sf2"
MUSIC_Init: trying ALSA
The simplest option here is to fetch this freely-available one and copy it to the same directory as duke3d.cfg
(normally ~/.jfduke3d
). Other places the game will search for .sf2
files include /usr/share/soundfonts
and /usr/share/sounds/sf2
, and the first one found will be used. When successfully installed, the messages from the game will look like so.
Checking music inits.
MUSIC_Init: trying FluidSynth
FluidSynthDrv: using version 2.1.7, built with 2.1.7
FluidSynthDrv: using found soundfont ./merlin_gold(v4.10).sf2
Now, if you still don't have music and see a message like fluidsynth: error: Failed to connect to Jack server then a different audio device needs to be set, and that means editing the duke3d.cfg
file. Find the line with MusicParams = ""
and between the quotes add audio.driver=sdl2
. Save the change, then start the game to test. If that doesn't work, try alternatives like audio.driver=pulseaudio
or audio.driver=portaudio
or audio.driver=alsa
or audio.driver=oss
.
Music Overrides
Ogg Vorbis alternatives to MIDI music can be automatically used by the game providing certain conditions are met. Files must have the same base filename as the MIDI track but with a .ogg
(lowercase) extension. For example, GRABBAG.ogg
will override GRABBAG.MID
, and dethtoll.ogg
will override dethtoll.mid
. Note that filename case may matter to you here.
On systems without filename case-sensitivity concerns, like Windows and typical macOS setups, you can copy the files to the same directory as duke3d.grp
or duke3d.cfg
. On case-sensitive filesystems though, the base part of the filename must match case as it is given in the game's USER.CON
file, noting that in the default Duke Nukem 3D game data the filenames are not consistent in their case. For instance, from Duke3D Atomic Ed.:
// Music for title and end
music 0 GRABBAG.MID BRIEFING.MID
// Music for the individual levels
music 1 stalker.mid dethtoll.mid streets.mid watrwld1.mid snake1.mid
thecall.mid ahgeez.mid dethtoll.mid streets.mid watrwld1.mid snake1.mid
music 2 futurmil.mid storm.mid gutwrnch.mid robocrep.mid stalag.mid
pizzed.mid alienz.mid xplasma.mid alfredh.mid gloomy.mid intents.mid
music 3 inhiding.mid FATCMDR.mid NAMES.MID subway.mid invader.mid gotham.mid
233c.mid lordofla.mid urban.mid spook.mid whomp.mid
music 4 missimp.mid prepd.mid bakedgds.mid cf.mid lemchill.mid
pob.mid warehaus.mid layers.mid floghorn.mid depart.mid restrict.mid
Having said all this, a quick way to avoid a lot of problems is to simply ZIP up the Vorbis files you want to use (e.g. as music.zip
), put that ZIP file in the same directory as duke3d.grp
or duke3d.cfg
, and launch the game with a -gmusic.zip
parameter as relevant to your operating system.
Multiplayer
Multiplayer games can be started from the startup window, or for more specialised situations, with command-line parameters passed to the game.
From the startup window, one player should choose "Host multi-player game" and select the number of players, then press Start to begin waiting. The other players should choose "Join multi-player game" and enter the hostname or IP address of the system hosting the game, and then press Start. The game will proceed once all players are joined.
The game communicates on UDP port 23513 by default, so if you intend to play across the Internet you may need to forward that port through relevant firewalls of the system hosting the game.
Command-line launching
The general command line syntax to use on each platform is:
- (Linux, in a terminal)
/path/to/jfduke3d/duke3d [options] -net [net options]
- (macOS, from a Terminal window)
open /Path/To/JFDuke3D.app --args [options] -net [net options]
- (Windows, from a Command Prompt window)
x:\path\to\jfduke3d\duke3d.exe [options] -net [net options]
Multiplayer games can use either of two communication modes: hosted (a.k.a. master/slave mode) and peer-to-peer. Peer-to-peer is more difficult to use over the Internet and more troublesome to correctly configure. In all modes you must know the exact number of players as the game will not start until all players are present.
Hosted (master/slave) mode
Choose a system to be the host of the game, and each other player will connect to that host.
The "net options" for this mode are:
-pportnum
— host the game on a different UDP port to the default 23513.-nm
— be host of a 2-player game.-nm:num
— be host of a num-player game.-nm host-name-or-ip
— join a game hosted by host-name-or-ip.-nm host-name-or-ip:port
— join a game hosted by host-name-or-ip on non-default port port.
For example, a three-player hosted game is launched like so:
- (Player 1, hosts)
duke3d -name Player1 -net -nm:3
- (Player 2, joins)
duke3d -name Player2 -net -nm host1
- (Player 3, joins)
duke3d -name Player3 -net -nm host1
Peer-to-peer mode
In this mode each player sends data to each other player in the game directly, which is only really practical in non-firewalled LAN-like environments. The list of peers specified on the command line must be consistently ordered amongst all players, and each peer will launch the game with slightly different options.
The "net options" for this mode are:
-pportnum
— communicate with other peers on a different UDP port to the default 23513.-np ordered-peer-list…
— participate in a peer-to-peer game..
or*
— identify the local machine in the ordered peer list.host-name-or-ip
— identify a peer at host-name-or-ip in the ordered peer list.host-name-or-ip:port
— identify a peer at host-name-or-ip on non-default port port in the ordered peer list.
For example, a three-player peer-to-peer game is launched like so:
- (Player 1)
duke3d -name Player1 -net -np . host2 host3
- (Player 2)
duke3d -name Player2 -net -np host1 . host3
- (Player 3)
duke3d -name Player3 -net -np host1 host2 .
NAM Support
Because it was trivial to do so, the commercial Duke3D-based game “NAM” is supported by JFDuke3D. Here is how to use it:
- Find the GAME.CON and NAM.GRP files from your copy of NAM.
- Rename GAME.CON to NAM.CON and put it in the JFDuke3D directory.
- Copy NAM.GRP to the JFDuke3D directory.
- Run JFDuke3D and select NAM from the Game tab in the "Game or Addon" list. If you have disabled the startup window from automatically showing, you can run DUKE3D.EXE passing the
-setup
switch to display it, or enable the "Show startup window" option in the Options → Game Options menu inside the game, or you can run DUKE3D.EXE passing the-nam
to enable NAM mode directly.
Console Commands
This is a list of more useful console commands and settings and their purpose:
- changelevel episode level
- Warps to a new level.
- clear
- Clear the console.
- glinfo
- Displays some information about the OpenGL driver. Use "glinfo exts" to display supported OpenGL extensions.
- glmultisample samples
- Enable OpenGL multisample antialiasing. 0 disables it, 1 and higher enable. You need to use "restartvid" to apply any changes to this value.
- gltextureanisotropy level
- Sets the OpenGL anisotropic filtering level. The default is the highest level supported by the hardware.
- gltexturemode mode-number
Sets the OpenGL texturing mode. Valid values are:
mode-number Mode 0 GL_NEAREST 1 GL_LINEAR 2 GL_NEAREST_MIPMAP_NEAREST 3 GL_LINEAR_MIPMAP_NEAREST (bilinear) 4 GL_NEAREST_MIPMAP_LINEAR (gives an unfiltered appearance like the original software renderer) 5 GL_LINEAR_MIPMAP_LINEAR (trilinear, the default) - glusetexcompr 0|1
- Enables or disables the use of OpenGL texture compression for replacement textures. You need to use "restartvid" to apply any changes to this value.
- god
- Enables God mode.
- help symbol-name
- Displays a help message for a particular console variable or command.
- listsymbols
- Displays the names of all commands and variables available in the console.
- map mapname
- Loads a user map.
- noclip
- Disables player collisions with world objects.
- novoxmips 0|1
- Disables or enables the use of voxel mipmaps to improve voxel visual quality.
- osdrows num
- Sets the number of visible lines of the console when it is open.
- restartvid
- Reinitialise video to apply settings changes.
- screencaptureformat 0|1
- 0 = Targa, 1 = PCX
- usegoodalpha 0|1
- If 1, a lower alpha cutoff value is used when rendering textures with transparency, which gives better looking transparent textures at the expense of some sprites behind the transparent item potentially being invisible in certain circumstances. 0 is a more compatible value (and is the default) for this option but slight visual degradation will result.
- vidmode bpp
- vidmode xdim ydim [bpp [fs]]
- Change the video mode. xdim ydim are the resolution. bpp is the colour depth (8, 16, 24, 32). fs is 0 for windowed, 1 for fullscreen.
License
JFDuke3D is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
See the GNU General Public License for more details.
The JFBuild engine used in JFDuke3D is used under the terms of the BUILD Source Code License.