ACKNEX REBORN 0.2 (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


CONTENTS
--------

  1. Features
  2. Getting started
  3. Launcher options
  4. The in-game panel
  5. Troubleshooting
  6. About


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

Native Windows and Linux
  64-bit builds, cross-compatible engine.

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 old bugs
  Issues that only show up on today's computers are fixed, so games play
  the way they were meant to.

Plays more games
  Various compatible games.

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.
     With no arguments 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.

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

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)
      Reads a different data file instead of WWRUN.WDF.
  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.

The Run button stays greyed out until a script or an archive is chosen.


Devices
-------

  No sound (-OS)            Turns off sound effects.
  No music (-OM)            Turns off MIDI music.
  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)
      Stops waiting for the display. 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. The picture is scaled to fit it. Default 1600 x
      1200.


Network
-------

Two players can play games that support it, over the local network or the
internet.

  NOTE: Network play is very limited for now: two players only, and only
  in games that were made for it. There are plans to expand it in future
  versions.

  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)
      Node 0 uses this port and node 1 the next one. Both players need the
      same value. 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 are the options ACKNEX Reborn adds to the original engine. Options
marked [OpenGL] only work with the OpenGL renderer on, and are greyed out
without it.

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.
  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
        The movement keys also reach the game, for cheats and keys it
        reads itself. Some games then do two things at once; turn it off
        if W, A, S or D does something odd while you walk. Only
        available with "Modern WASD movement" on.
  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
      16 is the speed the games were made for. 32 or more is smoother;
      keep the texture fix on with it.
  Smooth movement between steps (-INTERP)                        On
      Smooths movement between steps, for high refresh rate displays. Adds
      a tiny delay.
  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; 400% matches the games running at 16 frames
      a second.
  Fix walking through walls at corners (-FWALL)                  On
      Stops the player slipping through walls at some corners.

Compatibility                                                    Default

  CD music from .ogg files (-OGGCD)                              On
      Plays track2.ogg, track3.ogg... from the game's folder instead of
      the CD.
  Load game patches (-PATCH)                                     On
      Uses fixed or replacement files from an acknexpatch folder.
  Engine default keys (-IWDL)                                    On
      Adds the engine's default keys, such as F10 to quit. A game's own
      keys win.
  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
      Makes games made for the 1995 V3.08 engine version play correctly.
      Known V3.08 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. In each row, pressing the key on the right also
      presses the key on the left. The right key keeps doing what it did
      before. Either side can be a mouse button.

The "..." button next to a key lets you press the key instead of choosing
it from the list (Windows only). The default rebinding rows give most A3
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"
  The engine only accepts short file names, as in the 1990s. 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
  Windows SmartScreen shows "Windows protected your PC" for any program
  that has no digital signature and that few people have downloaded yet.
  It is not saying it found anything harmful. The beta builds are not
  signed yet, and each new build starts with no reputation again.
  - 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: some antivirus programs flag new, unsigned games
  and tools on sight.
  - 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
  Some games turn the camera themselves, and mouse look takes that control
  away. Turn off "Mouse look", and "Modern WASD movement" if the controls
  also feel wrong. Games known to need this get the right settings
  automatically.

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
  "Modern WASD movement" keeps W, A, S and D for walking, so a cheat
  that uses one of them (Incidente em Varginha's PCGOD ends on D) never
  arrives. Make sure "Trigger WASD events" is on (it is by default), 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. ABOUT
========

ACKNEX Reborn 0.2

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