ACKNEX REBORN 0.4 (Beta)
========================

Play classic 3D GameStudio A3 games on modern Windows and Linux, with
widescreen, mouse look and smooth high frame rates.

ACKNEX Reborn is a native port of the ACKNEX 3 engine, the runtime behind
games made with 3D GameStudio A3 in the late 1990s. It runs those games
directly on today's systems, with no DOS box or Windows 98 needed. You can
play them just as they looked in 1998, or turn on modern graphics and
controls.

Games are not included: you need the game's own files.
Questions and bug reports: https://discord.gg/Fdz6kjX8Jk

Website: https://rickomax.github.io/acknex-reborn


WHAT'S NEW IN 0.4
-----------------

  - Modded graphics: put PNG images in a game's "mod" folder to replace
    its textures, sprites, sky, panels, fonts and model skins, at any
    resolution (see 7. Modded graphics).
  - Panels, text and the mouse pointer are drawn with OpenGL too.
  - Windows MIDI: on Windows, MIDI music now plays through Windows' own
    synthesizer by default, so it sounds the way the games sounded when
    they came out. The built-in synthesizer is still there: turn off
    "Windows MIDI" on the Devices tab.
  - MIDI music can use a SoundFont (.sf2) of your choice.
  - Saints of Virtue: plays its ending video from INSTALL.MPG, made from
    the CD's INSTALL.DAT (see 6. Game videos).
  - A video converter that makes the game videos' .MPG files, in the
    releases area of our Discord (see 6. Game videos).
  - Black Bekker: the "no signal" screen covers the mini map in OpenGL.
  - OpenGL: signs and other wall decals no longer flicker or break up at a
    distance.


CONTENTS
--------

  1. Features
  2. Getting started
  3. Launcher options
  4. The in-game panel
  5. Troubleshooting
  6. Game videos
  7. Modded graphics
  8. About


1. FEATURES
===========

Native Windows and Linux
  64-bit builds for both.

Two renderers
  A new OpenGL renderer, or the original software renderer. Switch between
  them while you play.

Widescreen and any resolution
  Fill the whole screen, at any window size up to 4K and beyond.

Better graphics
  Filtered textures, optional ambient occlusion and an adjustable field of
  view.

Modern controls
  Mouse look, WASD movement, key rebinding, and joystick look and button
  bindings.

Smooth at high frame rates
  Games run at a constant speed on every device.

Fixes for modern computers
  Issues that only show up on today's computers are fixed, so games play
  the way they were meant to.

Many compatible games
  See the list on the project page.

Easy launcher
  Pick a game, choose your options and play.

In-game panel
  Press F11 while playing to change options.


2. GETTING STARTED
==================

  1. Extract the package to a folder of its own, for example
     C:\Games\ACKNEX Reborn or ~/acknex-reborn.
  2. Start it. Run acknexreborn.exe on Windows, or acknexreborn on Linux.
     It opens the launcher.
  3. Pick the game. On the Game tab, press Browse next to Script and choose
     the game's .WDL file. For a game shipped as one archive, choose its
     .WRS file under Archive instead. The game's folder is filled in for
     you.
  4. Press Run. Your choices are saved and will be there next time.

For most of the compatible games listed on the project page there is a
quicker way: extract the package into the game's own folder and run
acknexreborn there. The game starts straight away. A few games first ask
about their own options, such as the language or skipping the intro.

While playing:

  F11          Opens the in-game panel (you can change this key in the
               launcher)
  Alt+Enter    Switches between fullscreen and a window
  F10          Quits, in most games

You can also skip the launcher and start a game from its folder:

  acknexreborn GAME.WDL [switches]

followed by any of the switches listed below, for example:

  acknexreborn GAME.WDL -GL -WS -ML

For one of the compatible games you can name its folder instead, from
anywhere:

  acknexreborn D:\games\hades2

Settings from the launcher still apply; switches on the command line win.


3. LAUNCHER OPTIONS
===================

Every option in the launcher also has a command-line switch, shown in
brackets in the launcher and below. The Command line box at the bottom of
the launcher shows exactly what will be used. "Reset settings..." puts
everything back to the defaults listed here. Hover over any option in the
launcher for a short description.


Game
----

  Script (-WDL)
      The game's main script (.WDL) to run.
  Archive (-WRS)
      The game's resource archive (.WRS), for games shipped as one file.
  Map (-WMP)
      Loads a different map instead of the one the game names.
  Data file (-WDF)
      Uses a different data file. Only needed if a game's instructions ask
      for it.
  Game folder
      The game's folder. Filled in when you pick a file with Browse.
  Save path (-DIR)
      Where saved games go.
  Define (-D name,value)
      Passes a setting to the game. Only needed if a game's instructions
      ask for it.
  Error limit (-E)
      Keeps going past this many script errors instead of stopping at the
      first.


Devices
-------

  No sound (-OS)            Turns off sound effects.
  No music (-OM)            Turns off MIDI music.
  Windows MIDI (-WINMIDI)   Plays MIDI music through Windows' own
                            synthesizer instead of the built-in one.
                            Windows only. On by default.
  SoundFont (-SOUNDFONT)    A .sf2 file to play MIDI music with. Empty uses
                            FluidR3_GM.sf2. Not used with Windows MIDI.
  No CD audio (-OCD)        Turns off CD audio.
  No audio at all (-OT)     Turns off all sound and music at once.
  No joystick (-NJ)         Ignores any joystick.
  No mouse (-NM)            Ignores the mouse.
  Sound volume (-SVOL)      Sound effects volume, in percent. Default 100.
  Music volume (-MVOL)      Music volume, in percent. Default 100.


Display
-------

  Start in a window (-WND)
      Starts in a window instead of fullscreen. On by default.
  Show the console (-CONSOLE)
      Opens a window with the engine's messages. Useful when reporting a
      problem.
  Exclusive fullscreen (-FSEXCL)
      Fullscreen changes the monitor's resolution. Off: borderless
      fullscreen at desktop resolution.
  Fullscreen as a window (-FSWIN)
      Fullscreen as a borderless window. Use it if the Windows Game Bar or
      another overlay doesn't appear over the game.
  No vsync (-NVSYNC)
      Turns off vsync. Very high frame rates can break some games.
  Frame cap when vsync is off (-MAXFPS)
      Limits the frame rate while vsync is off. Default 500; 0 is no limit.
  Window size (-RESW / -RESH)
      The window's size. Default 1600 x 1200.


Network
-------

Two players can play games made for network play, over the local network
or the internet.

  Node number (-NODE)
      Starts a two-player game. One player picks node 0, the other node 1.
  Player name (-PLAYER)
      Your name in a network game.
  Peer address (-NETIP)
      The other player's address. Leave it empty to find them on the local
      network.
  Base port (-NETPORT)
      Both players need the same value. For internet play, open this port
      and the next one. Default 2300.


Demo
----

Records what you play to WDLTape.REC in the game's folder with "Record a
demo" (-R), and plays it back with "Replay a demo" (-P).


Enhancements
------------

These options are new in ACKNEX Reborn. Options marked [OpenGL] need the
OpenGL renderer.

Graphics                                                         Default

  OpenGL renderer (-GL)                                          On
      Draws with OpenGL instead of the original software renderer.
  Override the field of view (-FOV)                              Off, 90
      Sets the field of view in degrees. The game's own zoom effects stop
      working.
  Widescreen (-WS) [OpenGL]                                      On
      Fills the whole window instead of 4:3 with black bars.
  Stretch the HUD to the widescreen (-SHUD) [OpenGL]             On
      Stretches the HUD across the wide view instead of keeping it 4:3.
  Ambient occlusion (-SSAO) [OpenGL]                             Off
      Darkens corners and creases for extra depth. Costs GPU time. Radius
      and Strength set how far and how dark.
  Smooth distant textures (-MIPMAPS) [OpenGL]                    On
      Smooths distant textures and stops shimmering. Uses more memory.
  Smooth fog (-SMOOTHFOG) [OpenGL]                               On
      Distant surfaces fade into darkness smoothly instead of in bands.
  2D layer in OpenGL (-GL2D) [OpenGL]                            On
      Draws panels, text and the mouse pointer with OpenGL as well.
  Modded graphics (-MODS) [OpenGL]                               On
      Uses replacement PNG images from the game's "mod" folder (see
      7. Modded graphics).
  Show FPS (-FPS)                                                Off
      Shows the frame rate in the corner of the view.

Input                                                            Default

  Mouse look (-ML)                                               On
      Turns the view with the mouse, with separate X and Y sensitivity.
      Some cutscenes that turn the camera may not work.
  Modern WASD movement (-MI)                                     On
      The keys set on the Keys tab walk and sidestep, replacing the game's
      own movement.
    Trigger WASD events (-MIEV)                                  On
        W, A, S and D still work for the game's own keys, such as cheats.
        Turn it off if one of them does something odd while you walk.
  Pin the cursor to the view's centre (-CURLOCK)                 Off
      Keeps the cursor on the crosshair, so clicks hit what you face.

Timing and physics                                               Default

  Fixed game speed (-DETERMINISTIC)                              On
      The game runs at a fixed rate, the same on every computer.
  Steps per second (-SIMHZ)                                      32
      Higher is smoother.
  Smooth movement between steps (-INTERP)                        On
      Smoother motion on high refresh rate displays.
  Fix texture animation speed (-FCD)                             On
      Animated textures run at their intended speed, not as fast as the
      frame rate.
  Fix jumps and falls (-FVZ)                                     Off, 400%
      Jumps and falls behave the same at any frame rate. "Jump and fall
      strength" adjusts them.
  Fix walking through walls at corners (-FWALL)                  On
      Stops the player slipping through walls at some corners.
  Don't fall through narrow gaps (-FEDGE)                        Off
      Stops the player falling into gaps narrower than they are.

Compatibility                                                    Default

  CD music from .ogg files (-OGGCD)                              On
      Plays track2.ogg, track3.ogg... from the game's folder instead of
      the CD.
  Play game videos (-VIDEOS)                                     On
      Plays a game's videos from .MPG files in its folder. Any key skips.
    Video volume, percent (-VVOL)                                100
      Volume of the game videos' sound.
  Load game patches (-PATCH)                                     On
      Applies ACKNEX Reborn's fixes for some games.
  Engine default keys (-IWDL)                                    On
      Adds standard keys such as F10 to quit, unless the game uses them
      itself.
  Support games for engine V3.680 (-V368)                        On
      Lets games made for the older V3.680 engine load.
  Support games for engine V3.56 (-V356)                         On
      Lets games made for the older V3.56 engine load.
  Support games for engine V3.08 (-V308)                         Off
      For some games from 1995. Known games turn it on by themselves;
      leave it off for others.

Some games need particular settings to work, for example with mouse look
off. ACKNEX Reborn recognises these games and applies those settings for
you.


Keys
----

  Open the in-game panel                                         F11
      The key that opens the in-game panel.
  Modern WASD movement keys                                      W S A D
      Walk forward, walk backward, strafe left, strafe right. Used when
      "Modern WASD movement" is on.
  Key rebinding (-REBIND)                                        On
      A list of rows, each making one key or mouse button also press
      another. The key you press keeps doing what it did before.

The "..." button next to a key lets you press the key instead of choosing
it from the list (Windows only). The default rows give most games modern
controls:

  Press               Also presses    Usually means
  -----------------   ------------    --------------------------------
  Space               Home            Jump
  C                   End             Duck
  E                   Space           Use / open
  F                   E               Whatever E did before
  Left mouse button   Ctrl            Fire


Joystick
--------

  Turn the view with the stick (-JL)                             Off
      Turns the view with a second stick.
  Look axis X / Y (-JLAX / -JLAY)                                3 and 4
      Which axes turn the view.
  Yaw / Pitch speed (-JLX / -JLY)                                100%
      100% is one full turn a second with the stick pushed all the way.
  Deadzone (-JLDZ)                                               8%
      Ignores small stick movements near the centre.
  Invert pitch (-JLINV)                                          Off
      Flips up and down.
  Strafe instead of turning (-JSTRAFE)                           Off
      Pushing the stick left or right sidesteps instead of turning. Use it
      with joystick look or mouse look.
  Strafe axis X / Y (-JSAX / -JSAY)                              0 and 1
      Which axes walk and sidestep.
  Joystick bindings (-JBIND)                                     Off
      A list of rows, each making a button or trigger press a key. A
      trigger counts as an axis: pick "Axis +" and its number.

When joystick bindings are turned on, the default rows are: right trigger
presses Ctrl, the bottom face button presses Space, and the left face button
presses E. To find a stick's axis and button numbers, open the in-game
panel's Joystick tab, which shows each axis and button live.


4. THE IN-GAME PANEL
====================

Press F11 while playing to open the panel. It has most of the launcher's
options, and changes apply right away. They are saved for the next time you
play.


5. TROUBLESHOOTING
==================

The Run button is greyed out
  Choose the game first: on the Game tab, use Browse to pick the game's
  .WDL script or .WRS archive.

"The script name is longer than 12 characters"
  Use Browse rather than typing a path: it puts just the file name in the
  box and the folder in "Game folder".

Windows warns that the program is from an unknown publisher
  The beta builds are not signed yet; the warning does not mean anything
  harmful was found.
  - Choose "More info", then "Run anyway".
  - Or, before unpacking, right-click the downloaded .zip, choose
    Properties, tick "Unblock" and press OK. Files unpacked from it will
    then start without the warning.

Windows Defender or another antivirus removes or blocks the program
  This is a false alarm.
  - Download ACKNEX Reborn only from the website or Discord linked below.
  - Restore the file from quarantine (Windows Security > Virus & threat
    protection > Protection history) and allow it.
  - You can report the false alarm to Microsoft at
    https://www.microsoft.com/wdsi/filesubmission, and let us know on
    Discord so we can follow it up.

On Linux, nothing happens when I start it
  - Make sure the file is executable: chmod +x acknexreborn
  - Start it from a terminal to see any error message.
  - The launcher needs GTK 3, which most desktops already have. You can
    also skip the launcher and start a game directly: ./acknexreborn GAME.WDL

The game stops with a script error while loading
  - Check that "Support games for engine V3.680" and "V3.56" are on
    (Enhancements tab). Many older games need one of them. For a game from
    1995, also try "V3.08".
  - If the game still stops, turn on "Error limit" on the Game tab and set
    it to a few errors, so the game keeps going past them.
  - Please report the game on Discord, with the error message.

A cutscene freezes, or the camera doesn't turn when the game wants it to
  Turn off "Mouse look", and "Modern WASD movement" if the controls also
  feel wrong.

The controls don't match the game's instructions
  "Modern WASD movement" and "Key rebinding" change the controls on
  purpose. To play with the game's original controls, turn both off. To
  change a single key, edit the rows on the Keys tab.

A cheat or a typed word doesn't work
  Make sure "Trigger WASD events" is on (Enhancements tab), or turn
  "Modern WASD movement" off.

The game runs too fast, or animations are too fast
  Keep "Fixed game speed" and "Fix texture animation speed" on, and leave
  vsync on ("No vsync" off). If you turned vsync off,
  set "Frame cap when vsync is off" to a normal value such as 144.

Jumps are too high or too low
  Turn on "Fix jumps and falls" (Enhancements tab) and adjust "Jump and
  fall strength". You can do this live in the in-game panel (F11) to find
  the right value for a game.

Widescreen, ambient occlusion or other graphics options are greyed out
  Those options only work with the "OpenGL renderer". Turn it on first.

I can't open the Windows Game Bar
  Turn on "Fullscreen as a window" (Display tab).

The game stutters or runs slowly
  - Turn off "Ambient occlusion", which costs the most.
  - Try a smaller window size, or turn off "Smooth distant textures".
  - Update your graphics driver.
  - If it happens only in OpenGL, try the original software renderer (turn
    off "OpenGL renderer").

There is no music
  - For MIDI music, keep FluidR3_GM.sf2 in the same folder as acknexreborn.
  - For CD music, copy the CD's audio tracks into the game's folder as
    track2.ogg, track3.ogg and so on (the same numbers as on the CD), and
    keep "CD music from .ogg files" on.
  - Check that "Music volume" is above 0 and that "No music" and "No audio
    at all" are off.

Mouse clicks miss what I'm aiming at
  Turn on "Pin the cursor to the view's centre", so clicks land on the
  crosshair while mouse look is on.

Two-player games can't find each other
  - One player must be node 0 and the other node 1.
  - Both must use the same "Base port".
  - Enter the other player's address, or leave it empty on the same local
    network.
  - Allow the program through your firewall (it uses UDP).

I changed too many settings and want to start over
  Press "Reset settings..." in the launcher. Your settings are stored in
  wwrun.cfg next to the program; deleting that file does the same.

The game crashed
  Note the message in the crash window, turn on "Show the console" on the
  Display tab, and try again. Then report it on Discord
  (https://discord.gg/Fdz6kjX8Jk) with the game's name, what you were doing
  and what the console showed.


6. GAME VIDEOS
==============

Some games' videos have to be converted to .MPG files before ACKNEX Reborn
can play them. Put the files in the game's folder. Any key skips a video.

  Incidente em Varginha, Alien Anarchy    INTRO01.MPG, INTRO02.MPG, END01.MPG
  Saints of Virtue, Saints of Virtue X    INTRO.MPG, INSTALL.MPG (the ending)

Making the files

Use the ACKNEX Reborn video converter, in the releases area of our
Discord (https://discord.gg/Fdz6kjX8Jk). Choose the game's original
files or its CD image, and it finds the videos above and converts them. It
can download FFmpeg for you.

The videos must come from your own, legally obtained copy of the game.

These files are for your personal use. ACKNEX Reborn does not distribute
them, and ACKNEX Reborn, its developers and contributors are not
responsible for unauthorised or illegal redistribution of copyrighted game
files.


7. MODDED GRAPHICS
==================

With the OpenGL renderer, a game's images can be replaced by PNG files at
any resolution. Put them in a folder named "mod" in the game's folder.

A PNG replaces a whole image file and is named after it. mod/STONE.png
replaces STONE.PCX (or STONE.LBM, STONE.BBM) wherever the game shows it:
walls, floors, sprites, the sky, panels, fonts and the mouse pointer. Upper
or lower case does not matter.

Draw it at a multiple of the original size. For a 64 x 64 STONE.PCX, a
256 x 256 STONE.png is four times as detailed. Keep the same shape: a PNG
of another shape is stretched to fit.

One file often holds many pictures, and the PNG keeps them all in the same
places. Black Bekker cuts sixteen 40 x 40 frames out of its 160 x 160
KK_G005.pcx; a 640 x 640 KK_G005.png with each frame where it was, four
times larger, replaces all sixteen.

Transparency comes from the PNG's alpha channel, so edges can be soft
instead of the original's hard cut-outs.

The same name in two archives: a PNG in a subfolder named after a .WRS
file is used only for that archive's images. Incidente em Varginha has a
different FCT01.PCX in INTRO.WRS and in GAME.WRS, so one replacement goes
in mod/INTRO/FCT01.png and the other in mod/GAME/FCT01.png (or in
mod/FCT01.png, which serves every archive).

Model skins are named after the model and the skin's number: skin 0 of
CHAIR.MDL is mod/CHAIR_skin0.png, skin 1 is mod/CHAIR_skin1.png.

Example layout:

  the game's folder/
    GAME.WRS
    INTRO.WRS
    mod/
      STONE.png            replaces STONE.PCX, from any archive
      CHAIR_skin0.png      replaces skin 0 of CHAIR.MDL
      INTRO/
        FCT01.png          replaces FCT01.PCX from INTRO.WRS only

Good to know:

  - Shimmering water or lava stops shimmering when it is replaced.
  - Not replaced: animated model skins, FLIC animations and videos.
  - To check that a PNG is used, turn on "Show the console": it lists
    each one with the image it replaces, and says when one is stretched.
  - A game's images are usually packed in its .WRS files. Get them out
    with the WRS extractor, in the acknex-3-info channel of our Discord
    (https://discord.gg/Fdz6kjX8Jk), then convert the ones you want to
    change to PNG with any image editor.


8. ABOUT
========

ACKNEX Reborn 0.4

ACKNEX 3 (3D GameStudio 3) is (C) oP group Germany GmbH.

ACKNEX Reborn is developed and maintained by Ricardo Reis, with permission
from Johann Christian Lotter (oP group).

ACKNEX Reborn is free. It may not be sold, or included with anything that
is sold, without permission. The games it runs belong to their owners, and
ACKNEX Reborn includes none of them.

Special thanks to:

Johann Christian Lotter, creator of ACKNEX / 3D GameStudio, and the entire
ACKNEX Reborn community.

Third-party software:

  SDL 3 - zlib License
  SDL_mixer - zlib License
  TiMidity - Artistic License
  stb_vorbis - MIT License
  TinySoundFont - MIT License
  PL_MPEG - MIT License
  Dear ImGui - MIT License
  libui-ng - MIT License
  FluidR3_GM SoundFont, by Frank Wen and Toby Smithe - MIT License

Website:             https://rickomax.github.io/acknex-reborn
Discord:             https://discord.gg/Fdz6kjX8Jk
oP group:            https://www.opgroup.de
Support the project: https://ko-fi.com/X8X3MRF5W
