games/jfsw: Enhance script and documentation.

Signed-off-by: B. Watson <yalhcru@gmail.com>

10 files changed, 287 insertions, 20 deletions

diff --git a/games/jfsw/README b/games/jfsw/README
index e9b566f2a252..e15b0a810ecb 100644
--- a/games/jfsw/README
+++ b/games/jfsw/README
@@ -4,22 +4,38 @@ The aim of this port is to present Shadow Warrior as closely as possible
 to the original game while adding optional features to expand the
 possibilities of the game.
 
-To play the game, you will need the sw.grp data file from either the
-full or shareware DOS version of Shadow Warrior. If you want to play the
-shareware version, you can install jfsw_demo_data from slackbuilds.org.
-For the full version, copy sw.grp from the game directory to
-/usr/share/games/jfsw/sw.grp (the filename must be lowercase).
+To play the game, you will need at least one ".grp" game data file.
+Choices are:
 
-If you have sw.grp from the full version of the game, you may also want
-to install jfsw_hires_pack for some graphic enhancements (don't bother
-trying if all you have is the shareware sw.grp: it segfaults on startup).
+- jfsw_demo_data, the Demo/Shareware version. Only 4 levels.
+- jfsw_registered_data, the Full/Registered version. Complete game,
+  including the 4 levels from the demo.
+- jfsw_wanton_destruction, the Wanton Destruction expansion pack.
+  Includes 12 new levels, plus the 4 levels from the demo.
 
-Optional dependencies: SDL2 and/or fluidsynth. These will be autodetected
-and used if they are installed. SDL2 provides a slightly better user
-experience (YMMV), but fluidsynth doesn't actually seem to *do* anything
-for jfsw.
+Any or all of the game data packages can be installed at the same time
+without conflict.
+
+There is another expansion pack, Twin Dragon, which is not supported
+by jfsw.
+
+If you install the full version of the game, you may also want to install
+jfsw_hires_pack for some graphic enhancements. Don't bother trying if
+all you have is the shareware sw.grp: it segfaults on startup.
+
+Optional dependencies: SDL2 and/or fluidsynth. These will be autodetected.
+If you want to force building without them, you can export SDL2=no
+and/or FLUID=no in the environment. SDL2 provides a slightly better user
+experience (YMMV). See README_music.txt for details on using fluidsynth
+with jfsw.
+
+To get the in-game music to play, see README_music.txt.
 
 Note: If you run into an issue turning left or right with the mouse,
 edit the config file (~/.jfsw/sw.cfg) and change MouseAnalogAxes0 to
 "analog_turning" and MouseAnalogAxes1 to "analog_moving". The digital
 axes should have "" values.
+
+Note: I've had zero luck trying to run game mods with jfsw. If you get any
+mods working, I'd love to hear from you (email address in .info file),
+let me know how you did it.
diff --git a/games/jfsw/README_game_data.txt b/games/jfsw/README_game_data.txt
new file mode 100644
index 000000000000..d67b11c383dc
--- /dev/null
+++ b/games/jfsw/README_game_data.txt
@@ -0,0 +1,42 @@
+For the full version, you can copy SW.GRP from:
+
+- An installed copy of the DOS game.
+- The "swinst" directory of the install CD.
+- Download the game from GoG.com, free of charge (account creation
+  required). See: https://www.gog.com/game/shadow_warrior_complete
+- Download the game from Steam.
+- Simply install the jfsw_registered_data package from SBo.
+
+Copy the SW.GRP file to "/usr/share/games/jfsw/sw.grp".
+
+To get the in-game music working, see README_music.txt.
+
+The game engine checksums the files in /usr/share/games/jfsw/, so the
+filenames aren't really critical... except that they *must* be lowercase
+(game fails to start otherwise).
+
+jfsw can also play Wanton Destruction (WT.GRP), the expansion pack to
+Shadow Warrior that was originally developed in the 90s but never released
+commercially. In 2005, it was released as a freeware download. To play
+this version of the game, install jfsw_wanton_destruction.
+
+Possible .grp files:
+Registered sw.grp:  47536148 bytes, md5sum 9d200b5fb4ace8797e7f8638c4f96af2
+"Alternate" sw.grp: 47536148 bytes, md5sum 92006f69a15ffa5f48b7dcd07b75fda9
+Shareware sw.grp:   26056769 bytes, md5sum dafeec1b83bd31edc6dafffc9a75bdb8
+Wanton Destruction wt.grp: 48698128 bytes, d0f8dc0718127ca480abf14f3a9508c2
+
+If you have the "alternate" (hacked? pirated?) version of sw.grp, it
+differs by only a few bytes. jfsw will refuse to "see" it because the
+checksum doesn't match. You can convert it to the version jfsw expects,
+by running these commands (in bash or zsh) in the directory with the
+file in it:
+
+echo -ne '\x2f\x2f\x30\x2f\x30\x2f\x2f\x2f\x2f\x33\x36\xa6\x32\x33\x31\x30' | \
+          dd of=sw.grp conv=notrunc bs=1 seek=39170528
+echo -ne '\x30\xa4\x31\x31\x30\x30\x30\x30\x31\x31\x30\x30\x30\x31\x31\x31' | \
+          dd of=sw.grp conv=notrunc bs=1 seek=39170544
+
+The above may look like gibberish but it does work! Afterwards,
+double-check the length and md5sum of sw.grp. It should match the
+Registered version, above.
diff --git a/games/jfsw/README_music.txt b/games/jfsw/README_music.txt
new file mode 100644
index 000000000000..3150b75bd5bb
--- /dev/null
+++ b/games/jfsw/README_music.txt
@@ -0,0 +1,91 @@
+The most important things to understand about the music in Shadow Warrior:
+
+The demo/shareware version of the game uses MIDI. There are actually
+.MID files stored within sw.grp.
+
+The full/registered version and/or expansion pack uses CD audio
+tracks. They *can't* use MIDI: there's no MIDI data inside its .grp
+files at all.
+
+So there are 2 completely separate procedures for getting the music
+to work, depending on whether you're playing the full/expansion or
+demo version.
+
+Full (Registered) Version, Wanton Destruction expansion
+-------------------------------------------------------
+
+For these versions, jfsw doesn't actually support CD audio from a
+physical CD [*]. It does, however, support .ogg files made from the CD.
+You can use CD ripping software to rip these from the original CD,
+or download them (for free, account creation required) from:
+
+https://www.gog.com/game/shadow_warrior_complete
+
+...or download it from Steam (also for free). The same files are available
+there, under the name "Shadow Warrior Classic".
+
+The .ogg files should be named "track02.ogg" through "track14.ogg", all
+lowercase (there is NO "track01.ogg"!), and placed in either ~/.jfsw/
+or /usr/share/games/jfsw/
+
+Run the game, and the music should play. If not, use the in-game menus
+(Options, Sound Menu) to enable the music and turn up the volume.
+
+If you followed the steps below to get the demo music to play, you'll
+have to re-edit ~/.jfsw/sw.cfg and change the MusicDevice back to 0.
+
+If you're never going to play the demo version, there's no need to build
+jfsw with fluidsynth support (although, it won't hurt anything if you do).
+
+Note: When using the .ogg soundtrack, under some conditions, it seems
+the background music stops playing after loading a saved game. If this
+happens to you, toggle the music off & back on (under Options, Sound
+Menu), which should start it playing again.
+
+[*] There is some code in jfaudiolib that's supposed to play CD audio
+    but it's (a) SDL-1.2 only, and (b) broken.
+
+Demo (Shareware) Version
+------------------------
+
+For the shareware version, the MIDI data is already present inside the
+sw.grp file. To actually hear it, you'll have to:
+
+1. Build and install fluidsynth. Doesn't matter whether or not
+   optional jack-audio-connection-kit and/or lash are included (jfsw
+   doesn't use them though).
+
+2. Build and install fluid-soundfont.
+
+3. Build and install jfsw. When installing, the description should say
+   the package was built with fluidsynth.
+
+4. Run the game once, and exit it normally, to get it to create a config
+   file. You should now have a ~/.jfsw/sw.cfg file.
+
+5. Edit ~/.jfsw/sw.cfg, find the line that says "MusicDevice = 0", and
+   change the 0 to a 6. This enables fluidsynth.
+
+6. Run the game again. Make sure the music is enabled and the music
+   volume is turned up (under Options, Sound Menu).
+
+Unfortunately, the edited config file won't work with the full version.
+You'll have to change MusicDevice back to 0 (meaning 'autodetect') to get
+the .ogg tracks to play. Other possible values are 1 (SDL) and 7 (ALSA).
+
+There's no direct way to change which soundfont jfsw uses. What it does is
+look in /usr/share/sounds/sf2/ and pick the first soundfont it finds, in
+sorted order. Basically it does the C++ equivalent of:
+
+$ ls /usr/share/sounds/sf2/*.sf2 | head -1
+
+If the only sound fonts in that directory are the ones installed by
+the fluid-soundfont package, it will choose "FluidR3_GM.sf2", which is
+reasonable and sounds good.
+
+If you want to use a different soundfont, try something like this:
+
+# cd /usr/share/sounds/sf2/
+# ln -s MySoundFont.sf2 000-jfsw.sf2
+
+Check with the ls command above, to make sure 000-jfsw.sf2 sorts first.
diff --git a/games/jfsw/jfsw.SlackBuild b/games/jfsw/jfsw.SlackBuild
index 2d2fa28a3bd9..bf783c30a5e9 100644
--- a/games/jfsw/jfsw.SlackBuild
+++ b/games/jfsw/jfsw.SlackBuild
@@ -7,13 +7,21 @@
 
 # Licensed under the WTFPL. See http://www.wtfpl.net/txt/copying/ for details.
 
-# 20180710 bkw:
+# 20180710 bkw: BUILD=2
 # - updated for 20180424_8fc2d54 (latest git).
 # - finally fix long-standing segfault bug.
 # - document new optional deps in README.
 # - make slack-desc show runtime library deps.
-# - remove freepats from REQUIRES. I've never been able to get the
-#   music to play in jfsw anyway.
+# - remove freepats from REQUIRES. I've never been able to get
+#   jfsw to play music using them anyway.
+# - expand the section on the full-version sw.grp, move to
+#   separate README_game_data.txt. Found out about Wanton Destruction,
+#   it's now documented there too.
+# - add README_music.txt, explaining how to get the music working.
+#   turned out to be quite a lengthy project...
+# - expand README a bit, mention gog.com free download.
+# - allow fluidsynth builds to work even if fluidsynth built with JACK.
+# - add SDL2=no and FLUID=no build options.
 
 # When updating to the latest commit of jfsw, we gotta make sure we
 # get the correct commits of the other 3 sources (jfaudiolib, jfbuild,
@@ -30,7 +38,7 @@
 
 PRGNAM=jfsw
 VERSION=${VERSION:-20180424_8fc2d54}
-BUILD=${BUILD:-1}
+BUILD=${BUILD:-2}
 TAG=${TAG:-_SBo}
 
 if [ -z "$ARCH" ]; then
@@ -112,7 +120,29 @@ find -L . \
 # I came up with a band-aid to work around the segfault. Stops the
 # fire button from working the same as a Y keypress (or at all), in Y/N
 # prompts. Patch was sent upstream: https://github.com/jonof/jfsw/issues/14
-patch -p1 < $CWD/fixsegfault.diff
+patch -p1 < $CWD/patches/fixsegfault.diff
+
+# 20180712 bkw: one liner attempt to get SDL (1.2 only) CD-audio support
+# working.  It turns out there's something worse wrong, I can't even get
+# the example code from libsdl.org to play a CD (it'll list the tracks,
+# but SDL_CDPlayTracks() doesn't work, the drive won't even spin up).
+# Since this is SDL 1.2, not 2.x, any attempt to ask for help from an
+# SDL developer or expert is going to be answered with "port your code to
+# SDL 2.x!", so I'm just documenting CD support in jfsw as being broken.
+#patch -p1 < $CWD/patches/sdl_cdrom_fix.diff
+
+# 20180712 bkw: if fluidsynth happens to have been built with optional
+# JACK support, it'll be the default driver and jfsw will try to use it.
+# This doesn't actually work, so:
+patch -p1 < $CWD/patches/dont_use_jack.diff
+
+# 20180712 bkw: we have sdl.pc (not sdl1.pc) for SDL 1.2.x:
+patch -p1 < $CWD/patches/sdl1_fix.diff
+
+# 20180712 bkw: upstream doesn't provide a way to override autodetection
+# of SDL2 and fluidsynth, so I do it with a couple of patches:
+[ "${SDL2:-yes}" = "no" ] && patch -p1 < $CWD/patches/disable_sdl2.diff
+[ "${FLUID:-yes}" = "no" ] && patch -p1 < $CWD/patches/disable_fluid.diff
 
 # 20180711 bkw: The -Wno-return-type isn't needed for gcc but does no
 # harm. Left in place in case someone wants to build this with clang
@@ -120,7 +150,7 @@ patch -p1 < $CWD/fixsegfault.diff
 
 # 20180711 bkw: JFAUDIOLIB_USE_SDLMIXER=1 doesn't work (build fail due
 # to missing driver_sdlmixer.c). Maybe someday it'll work and then we
-# can maybe hear the in-game music? (or not?)
+# hear the demo music without having to install fluidsynth?
 
 make \
   RELEASE=1 \
@@ -128,8 +158,7 @@ make \
   CFLAGS="$SLKCFLAGS -Wno-return-type" \
   CXXFLAGS="$SLKCFLAGS"
 
-# So far, we haven't got options to disable the optional stuff, but
-# at least document what the binary package needs in its slack-desc.
+# Document what the binary package needs in its slack-desc.
 BIN_NAME=sw
 SDLVER=1.2
 WITHFLUID=without
diff --git a/games/jfsw/patches/disable_fluid.diff b/games/jfsw/patches/disable_fluid.diff
new file mode 100644
index 000000000000..970e8bd67aac
--- /dev/null
+++ b/games/jfsw/patches/disable_fluid.diff
@@ -0,0 +1,12 @@
+diff -Naur jfsw.orig/jfaudiolib/Makefile.shared jfsw/jfaudiolib/Makefile.shared
+--- jfsw.orig/jfaudiolib/Makefile.shared	2017-02-02 07:22:54.000000000 -0500
++++ jfsw/jfaudiolib/Makefile.shared	2018-07-12 15:25:01.996310856 -0400
+@@ -30,8 +30,4 @@
+   JFAUDIOLIB_LDFLAGS+= $(shell pkg-config --libs alsa)
+   JFAUDIOLIB_LDFLAGS+=-lpthread
+  endif
+- ifeq (yes,$(shell pkg-config --exists fluidsynth && echo yes))
+-  JFAUDIOLIB_HAVE_FLUIDSYNTH=1
+-  JFAUDIOLIB_LDFLAGS+= $(shell pkg-config --libs fluidsynth)
+- endif
+ endif
diff --git a/games/jfsw/patches/disable_sdl2.diff b/games/jfsw/patches/disable_sdl2.diff
new file mode 100644
index 000000000000..425402882671
--- /dev/null
+++ b/games/jfsw/patches/disable_sdl2.diff
@@ -0,0 +1,31 @@
+diff -Naur jfsw.orig2/jfaudiolib/Makefile.shared jfsw/jfaudiolib/Makefile.shared
+--- jfsw.orig2/jfaudiolib/Makefile.shared	2018-07-12 15:44:51.443280637 -0400
++++ jfsw/jfaudiolib/Makefile.shared	2018-07-12 15:43:41.666282410 -0400
+@@ -16,15 +16,10 @@
+   JFAUDIOLIB_HAVE_VORBIS=1
+   JFAUDIOLIB_LDFLAGS+= $(shell pkg-config --libs vorbisfile)
+  endif
+- ifeq (yes,$(shell pkg-config --exists sdl2 && echo yes))
+-  JFAUDIOLIB_HAVE_SDL=2
+-  JFAUDIOLIB_LDFLAGS+= $(shell pkg-config --libs sdl2)
+- else
+   ifeq (yes,$(shell pkg-config --exists sdl && echo yes))
+    JFAUDIOLIB_HAVE_SDL=1
+    JFAUDIOLIB_LDFLAGS+= $(shell pkg-config --libs sdl)
+   endif
+- endif
+  ifeq (yes,$(shell pkg-config --exists alsa && echo yes))
+   JFAUDIOLIB_HAVE_ALSA=1
+   JFAUDIOLIB_LDFLAGS+= $(shell pkg-config --libs alsa)
+diff -Naur jfsw.orig2/jfbuild/Makefile.shared jfsw/jfbuild/Makefile.shared
+--- jfsw.orig2/jfbuild/Makefile.shared	2017-02-04 02:45:28.000000000 -0500
++++ jfsw/jfbuild/Makefile.shared	2018-07-12 15:51:08.320271062 -0400
+@@ -9,7 +9,7 @@
+ GLLIBLIN=-lGL
+ 
+ SDLCONFIG=$(shell which sdl-config)
+-SDL2CONFIG=$(shell which sdl2-config)
++SDL2CONFIG=
+ 
+ # Path to the included libsquish
+ LIBSQUISH=libsquish
diff --git a/games/jfsw/patches/dont_use_jack.diff b/games/jfsw/patches/dont_use_jack.diff
new file mode 100644
index 000000000000..35dcbdb0172a
--- /dev/null
+++ b/games/jfsw/patches/dont_use_jack.diff
@@ -0,0 +1,14 @@
+diff -Naur jfsw.orig/jfaudiolib/src/driver_fluidsynth.c jfsw/jfaudiolib/src/driver_fluidsynth.c
+--- jfsw.orig/jfaudiolib/src/driver_fluidsynth.c	2017-02-02 07:22:54.000000000 -0500
++++ jfsw/jfaudiolib/src/driver_fluidsynth.c	2018-07-12 05:08:37.119250512 -0400
+@@ -342,6 +342,10 @@
+         return FSynthErr_Error;
+     }
+     
++	 /* 20180712 bkw: don't try to use JACK (it doesn't work) */
++	 if(fluid_settings_str_equal(fluidsettings, "audio.driver", "jack"))
++		 fluid_settings_setstr(fluidsettings, "audio.driver", "alsa");
++
+     fluidaudiodriver = new_fluid_audio_driver(fluidsettings, fluidsynth);
+     if (!fluidsettings) {
+         FluidSynthDrv_MIDI_Shutdown();
diff --git a/games/jfsw/fixsegfault.diff b/games/jfsw/patches/fixsegfault.diff
index 9290ffef9613..9290ffef9613 100644
--- a/games/jfsw/fixsegfault.diff
+++ b/games/jfsw/patches/fixsegfault.diff
diff --git a/games/jfsw/patches/sdl1_fix.diff b/games/jfsw/patches/sdl1_fix.diff
new file mode 100644
index 000000000000..1e68caab3376
--- /dev/null
+++ b/games/jfsw/patches/sdl1_fix.diff
@@ -0,0 +1,12 @@
+diff -Naur jfsw.orig/jfaudiolib/Makefile.shared jfsw/jfaudiolib/Makefile.shared
+--- jfsw.orig/jfaudiolib/Makefile.shared	2017-02-02 07:22:54.000000000 -0500
++++ jfsw/jfaudiolib/Makefile.shared	2018-07-12 15:31:55.593300348 -0400
+@@ -22,7 +22,7 @@
+  else
+   ifeq (yes,$(shell pkg-config --exists sdl && echo yes))
+    JFAUDIOLIB_HAVE_SDL=1
+-   JFAUDIOLIB_LDFLAGS+= $(shell pkg-config --libs sdl1)
++   JFAUDIOLIB_LDFLAGS+= $(shell pkg-config --libs sdl)
+   endif
+  endif
+  ifeq (yes,$(shell pkg-config --exists alsa && echo yes))
diff --git a/games/jfsw/patches/sdl_cdrom_fix.diff b/games/jfsw/patches/sdl_cdrom_fix.diff
new file mode 100644
index 000000000000..bffad4a76b27
--- /dev/null
+++ b/games/jfsw/patches/sdl_cdrom_fix.diff
@@ -0,0 +1,20 @@
+diff -Naur jfsw.orig/jfaudiolib/src/driver_sdl.c jfsw/jfaudiolib/src/driver_sdl.c
+--- jfsw.orig/jfaudiolib/src/driver_sdl.c	2017-02-02 07:22:54.000000000 -0500
++++ jfsw/jfaudiolib/src/driver_sdl.c	2018-07-12 17:08:14.907153516 -0400
+@@ -375,6 +375,7 @@
+ int SDLDrv_CD_Init(void)
+ {
+ #if (SDL_MAJOR_VERSION == 1)
++    CDstatus status;
+     Uint32 inited;
+     Uint32 err = 0;
+     int i;
+@@ -407,6 +408,8 @@
+         return SDLErr_Error;
+     }
+     
++    status = SDL_CDStatus(CDRom);
++
+     fprintf(stderr, "SDL_CD: numtracks: %d\n", CDRom->numtracks);
+     for (i = 0; i < CDRom->numtracks; i++) {
+         fprintf(stderr, "SDL_CD: track %d - %s, %dsec\n",