You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
125 lines
5.5 KiB
125 lines
5.5 KiB
# NetHack 3.7 code_features.txt $NHDT-Date: 1596498264 2020/08/03 23:44:24 $ $NHDT-Branch: NetHack-3.7 $:$NHDT-Revision: 1.6 $
|
|
# Copyright (c) 2015 by Michael Allison
|
|
# NetHack may be freely redistributed. See license for details.
|
|
|
|
Developer-useful info about code features, assumptions, purpose,
|
|
rationale, etc.
|
|
|
|
==============================================
|
|
FEATURE_NOTICE Alerts for a Release
|
|
|
|
There is a code mechanism for alerting players to a change in behavior
|
|
over prior versions of the game.
|
|
|
|
Here's how to do it:
|
|
o Where the change in behavior needs to alert the player,
|
|
- Add an 'if statement' to invoke the alert behavior
|
|
if the condition is met, for example
|
|
if (flags.suppress_alert < FEATURE_NOTICE_VER(3.6.0))
|
|
pline("Note: and explain the change here.");
|
|
- The example above will alert the users for a new feature
|
|
added in 3.6.0 via a one-liner via pline(), but you
|
|
could get more elaborate (just make sure it is all done
|
|
in the 'if' code block.
|
|
|
|
Once the user finds the alert no longer useful, or becoming
|
|
annoying, they can set the "suppress_alert" option.
|
|
- The user can only set the suppress_alert to the current
|
|
version, not future versions. That restriction is done
|
|
so that the feature can be used for new things in new
|
|
releases.
|
|
- The suppression can be done interactively mid game with
|
|
the 'O' command, or via
|
|
OPTIONS=suppress_alert:3.6.0
|
|
in the user's config file.
|
|
|
|
==============================================
|
|
PREFIXES_IN_USE and NOCWD_ASSUMPTIONS
|
|
|
|
Those provide a storage mechanism for holding the paths to various different
|
|
types of files. Those paths are stored in the fqn_prefix[] array. They are a
|
|
mechanism for enabling separation of the different files that NetHack needs.
|
|
|
|
The prefixes are added to the beginning of file names by various routines in
|
|
files.c immediately prior to opening one of the types of files that the game
|
|
uses.
|
|
|
|
They aren't about config file options (although config file options would be
|
|
one way to set non-default values for some of the paths in the fqn_prefix[]
|
|
array). Obviously the very first path needed (now sysconfdir, previously
|
|
configdir) isn't viable for setting via config file options, but the game
|
|
still needs to hunt it down "someplace." When the "someplace" is figured
|
|
out, that place (path) would be stored in fqn_prefix[SYSCONPREFIX]. How it
|
|
gets stored in fqn_prefix[SYSCONPREFIX] is up to us as developers.
|
|
|
|
Any of the fqn_prefix[] entries can be set somehow. It could be done in port
|
|
startup code; in options processing; in config file processing; by
|
|
translating a system environment variable such as USERPROFILE; whatever
|
|
you/we want. The point is that NOCWD_ASSUMPTIONS and PREFIXES_IN_USE are
|
|
there to ensure that there is a place to store that path information. The
|
|
code to *utilize* the information is already in files.c (see fqname()).
|
|
|
|
There is a fqn_prefix[] entry for holding the path to each of the following:
|
|
PREFIX NAME
|
|
0 HACKPREFIX hackdir
|
|
1 LEVELPREFIX leveldir location to create level files
|
|
2 SAVEPREFIX savedir location to create/read saved games
|
|
3 BONESPREFIX bonesir location to create/read bones
|
|
4 DATAPREFIX datadir location to read data.base etc.
|
|
5 SCOREPREFIX scoredir location to read/write scorefile
|
|
6 LOCKPREFIX lockdir location to create/read lock files
|
|
7 SYSCONFPREFIX sysconfdir location to read SYSCF_FILE
|
|
8 CONFIGPREFIX configdir location to read user configuration file
|
|
9 TROUBLEPREFIX troubledir location to place panic files etc.
|
|
|
|
To recap, they are about enabling "different paths for different things", and
|
|
separation of:
|
|
- read-only stuff from read-write stuff.
|
|
- sysadmin stuff from user-writable stuff.
|
|
etc.
|
|
|
|
==============================================
|
|
REGULAR EXPRESSIONS
|
|
|
|
There are multiple regular expression libraries supported. Currently, one (and
|
|
only one) of the following files should be linked into a built:
|
|
sys/share/cppregex.cpp
|
|
sys/share/posixregex.c
|
|
sys/share/pmatchregex.c
|
|
|
|
This provides a way to access different system regular expression libraries,
|
|
or fall back onto pmatch() if none is available. cppregex.cpp uses the regular
|
|
expression library in the C++11 standard, and is the default on Windows.
|
|
posixregex.c uses the POSIX regular expression library, and is the default on
|
|
POSIX. pmatchregex.c is the fallback.
|
|
|
|
Configuration files written using either of the two true regex engines are
|
|
compatible with one another, as the regular expressions are both POSIX
|
|
extended regular expressions. Configuration files written using the fallback
|
|
engine are incompatible.
|
|
|
|
Additional regular expression implementations can be written. The full
|
|
interface documentation is in sys/share/posixregex.c
|
|
|
|
===========================================================
|
|
HEADER FILE NOTES
|
|
|
|
hack.h defines values that are available to all NetHack source files,
|
|
contains enums for use in all NetHack source files, and contains a
|
|
number of struct definitions for use in all NetHack source files.
|
|
hack.h does not contain variable declarations or variable definitions.
|
|
|
|
decl.h and decl.c are related: decl.h contains the extern declarations
|
|
for variables that are defined in decl.c. These variables are global
|
|
and available to all NetHack source files.
|
|
decl.c variable definitions are generally laid out in much the same
|
|
order as their corresponding declarations in decl.h.
|
|
|
|
A new header file cstd.h was added to coincide with 3.7's switch to
|
|
C99. It contains calls to some C99 standard header files.
|
|
|
|
=================== NEXT FEATURE ==========================
|
|
|
|
|
|
|