Visit the JFDuke3D website for the latest information. The source code for JFDuke3D can be found in this Git repository.

# 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.15 (Catalina) 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+)

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

Windows, Linux and BSD (if built with GTK support) have similar startup windows with the same options.

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 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 downloaded an original 3D Realms distribution file named `3DDUKE13.ZIP`:

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

  Alternatively, you can fetch dn3dsw13.zip authenticity-intact from my site ready to unzip and point JFDuke3D at for importing.

## "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. Files may also be placed in a `music` subdirectory beside `duke3d.grp` if you prefer, and the entire filename may be lowercased if you are using a case-sensitive filesystem (e.g. typically Linux or BSD). For example, `grabbag.ogg` will override `GRABBAG.MID`, and `music/stalker.mid` will override `stalker.mid`.

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

Windows, Linux and BSD (if built with GTK support) have similar startup windows with the same options.

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 <0, 1, 2, …>
  Enable OpenGL multisample antialiasing. 0 disables it. 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:

  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 or 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 <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 or 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 or 1>
  0 = Targa, 1 = PCX, 2 = PNG (default)
usegammabrightness <0 or 1 or 2>
  Set brightness in one of several ways. 0 = palette-based, 1 = shader-based (default), 2 = system gamma. System gamma will brighten the whole display when in windowed mode.
usegoodalpha <0 or 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 [display]]]
  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. display is a display number for fullscreen mode, with 0 being the primary display.
maxrefreshfreq <0 or freq>
  Set the highest display refresh frequency for fullscreen OpenGL modes. 0 is the default representing 'no maximum'.

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