JFDuke3D Documentation

Index

• System Requirements
• Installation and Setup
• Music
• Multiplayer
• NAM Support
• Console Commands
• License

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.

1. Click the "Choose a location..." button, then navigate to a location where Duke Nukem 3D data can be found.
2. 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:

1. Unzip 3DDUKE13.ZIP to obtain the DN3DSW13.SHR file.
2. Rename DN3DSW13.SHR file to DN3DSW13.ZIP, then unzip it.

"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:

1. (Player 1, hosts) duke3d -name Player1 -net -nm:3
2. (Player 2, joins) duke3d -name Player2 -net -nm host1
3. (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:

1. (Player 1) duke3d -name Player1 -net -np . host2 host3
2. (Player 2) duke3d -name Player2 -net -np host1 . host3
3. (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:

1. Find the GAME.CON and NAM.GRP files from your copy of NAM.
2. Rename GAME.CON to NAM.CON and put it in the JFDuke3D directory.
3. Copy NAM.GRP to the JFDuke3D directory.
4. 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.