Skip to content

Windows NetHack 3.6.3 Breaking Change : Directory Paths

nhmall edited this page Dec 31, 2019 · 17 revisions

Overview

If you've downloaded the Windows 3.6.4 binary, read this first: file path and name changes on Windows

A Windows Store based release of NetHack was introduced, starting with NetHack 3.6.3. Due to limitations placed on Windows Store applications, we needed to revisit how we managed where NetHack accesses its various files and we have had to make several changes. These changes are described below.

Environment Variables

There are several environment variable that are used to help determine the directory paths.

  • USERNAME - set by the system, example "Bob"
  • SYSTEMDRIVE - set by the system, typically "C:"
  • USERPROFILE - %SYSTEMDRIVE%\Users%USERNAME%, example "C:\User\Bob"
  • ALLUSERPROFILE - %SYSTEMDRIVE%\ProgramData, example "C:\ProgramData"

NOTE: NetHack will no longer use the windows system environment variables "NETHACKDIR" and "HACKDIR". Below we will refer to the directory path HACKDIR. This is a directory path name that NetHack uses and should not be confused with the windows system environment variable called "HACKDIR". In previous versions of NetHack, the game would read the system environment variable "HACKDIR" in determining various directory paths. This is no longer the case.

Known Locations

There are several known locations that are used as part of determining the set of default directory paths NetHack will use.

  • EXECUTABLE_PATH - the directory that holds the executable
  • PROFILE_PATH - %USERPROFILE%\NetHack, example "C:\User\Bob\NetHack"
  • VERSIONED_PROFILE_PATH - %USERPROFILE%\NetHack, example "C:\User\Bob\NetHack\3.6"
  • USER_DATA_PATH - %USERPROFILE%\AppData\Local\NetHack\3.6, example "C:\User\Bob\AppData\Local\NetHack\3.6"
  • GLOBAL_DATA_PATH - %ALLUSERPROFILE%\NetHack\3.6, example "C:\ProgramData\NetHack\3.6"

Default directory paths

The game uses many directory paths in order to work with various files during game play. What follows are a description of these paths.

SYSCONFDIR

The SYSCONFDIR directory path is used to find the "sysconf" and "symbols" files. This path defaults to GLOBAL_DAT_PATH.

Upon game launch, the game will store the file "sysconf.template" and "symbols.template" in this directory. These files are example configuration files that the player can copy from.

Also upon launch, the game will write a default "sysconf" and "symbols" file to this directory if they do not exist.

Also upon game launch, the game will attempt replace the current "symbols" file with the latest "symbols.template" file if the template file is newer. The user will be prompted to ask whether the file should be replaced. If the user says yes, the "symbols" file will be replaced and a copy of the original "symbols" file will be saved to "symbols.save" in SYSCONFDIR. The user says no, the "symbols" file will remained unchanged but its modification date to avoid the user being prompted again.

CONFIGDIR

The CONFIGDIR directory path is used to find the ".nethackrc" file. This path defaults to PROFILE_PATH.

Upon game launch, the game will store the file ".nethackrc.template" in this directory. This file is an example file the player may copy from.

Also upon launch, the game will write a default ".nethackrc" file in this directory if it does not exist.

We expect the player to use the same ".nethackrc" files across various versions of the game.

HACKDIR

The HACKDIR directory path is used to store "Guidebookt.txt" and "opthelp". This path defaults to VERSIONED_PROFILE_PATH.

Upon game launch, the game will copy the latest "Guidebook.txt", "opthelp" files to this directory for the player's use.

SAVEDIR

The SAVEDIR directory path is where NetHack will store all saved game files. This path defaults to USER_DATA_PATH.

LEVELDIR

The LEVELDIR directory path is where NetHack will store the temporary level files during game play. This path defaults to USER_DATA_PATH.

BONESDIR

The BONES directory path is where NetHack will store all bone files. These files are by default shared among all the players on the machine. This path defaults to GLOBAL_DATA_PATH.

SCOREDIR

The SCOREDIR directory path is used by NetHack to stores files that are shared among all the players on the machine which record game results. These files are named "record", "logfile" and "xlogfile". This path defaults to GLOBAL_DATA_PATH.

LOCKDIR

The LOCKDIR directory path is used internally by NetHack during game play to help manage game file access by multiple users playing on the same system. This path defaults to GLOBAL_DATA_PATH.

TROUBLEDIR

The TROUBLEDIR directory path is used by NetHack to write diagnostics to a file named "paniclog". This file contains information about trouble the game was having during game play. If the game crashes due to a "panic", the reason for the panic will be saved to this file. The TROUBLDIR path defaults to VERSIONED_PROFILE_PATH.

DATADIR

The DATDIR directory path is used to find the various data files the game needs. This path is set to EXECUTABLE_PATH and can not be changed.

Environment variable option parsing

Upon game launch, NetHack will parse any options specified by the NETHACKOPTIONS environment variable. If the NETHACKOPTIONS environment variable is not defined, NetHack will also attempt to parse any options specified by the HACKOPTIONS environment variable. This allows the player to override all the directory paths with the exception of SYSCONFDIR and DATADIR.

Directory Overrides

Some of the directory paths can be changed. Below we describe how they can be changed.

SYSCONFDIR, DATADIR - cannot be changed

TROUBLEDIR, CONFIGDIR - can be changed using "sysconf" configuration file or the "NETHACKOPTIONS" environment variable

HACKDIR, SAVEDIR, BONESDIR, SCOREDIR, LOCKDIR - can be changed using "sysconf" or ".nethackrc" configuration files or changed using the "NETHACKOPTIONS" environment variable