Onslaught CE V0.1.12

Quick start
1. Extract the download into a new empty folder outside your original game folder. Preserve old installations
   and user folders; do not overwrite them or start a 0.1.0-0.1.6 launcher. You can move the new folder later.
2. Run onslaught-ce.exe.
3. It finds your Steam copy of Battle Engine Aquila by itself, or asks once where it is.

Keep the program and its user folder separate from the original game. By default, careers and settings go to
%APPDATA%\Onslaught CE. Keep recovery copies before changing save locations; do not point BEA_USER_DIR into the
game folder.
Preserve old program and staging folders during the launcher safety hold; keep verified user-data backups.

A native source port of Battle Engine Aquila (2003). It contains no game files: you need your own
copy of the game (for example from Steam).
Project page, source and releases: https://github.com/dlprentice/onslaught-ce

Start onslaught-ce.exe. (bea.exe also runs directly, without the install search.)
It needs Windows 10 or newer, for its built-in UCRT, and Windows 10 version 1903 or newer
for user or game folder names with characters outside your Windows language's character set (earlier
versions ignore the UTF-8 setting the programs ask for).
It finds your Battle Engine Aquila install in Steam's libraries, or asks you once for its folder and
remembers it (BEA_GAME_DIR overrides). By default, careers and settings go to a separate user folder:
%APPDATA%\Onslaught CE.
BEA_USER_DIR overrides that location. Keep it separate from the game folder and avoid linked paths.
Updates: at start it checks a signed feed (ce-update-v2.json) and asks before installing. A new version
goes into versions/ inside this folder; this folder's own files and everything beside it are left alone.
--update-only checks now, --rollback returns to the previous version, BEA_NO_UPDATE_CHECK=1 or
update_check=0 in ce.ini turns checking off. --apply is refused.
Do not start an Onslaught CE 0.1.0-0.1.6 launcher at all, not even to check its version or update it: its
startup cleanup can delete neighbouring <program folder>.old-* paths. On Linux it has followed a matching
directory link into its target; Windows reparse-point behaviour is unmeasured. Keep the old installation
and every .old-*, .download-* and .unpack-* path untouched.
Locate and preserve both launcher and game user-data folders. A relative BEA_USER_DIR can put them in
different locations. Copy each whole folder to an independent backup; verify the copies and careers.
If your data was in the default folder and its backup is verified, this release can use it as it is.
Otherwise use a separate working copy of the game's user-data folder outside the original game and old CE
program/staging folders; set BEA_USER_DIR to its absolute path. Check careers; keep originals and backups.
If the locations or conflicting files are unclear, do not merge or overwrite them; seek help first.
This release's launcher removes no neighbouring paths: verify its package and extract it into a new empty
folder. See the project README for full migration steps. No telemetry; the update check sends requests
for the public feed and its signature.
Report a problem opens a GitHub page in your browser with your version and OS in its address;
nothing is posted until you submit it.
Windows builds have been checked under Wine on Linux and on one Windows 11 virtual machine using software
graphics; this version's release notes list the routes checked for it. See also Known limitations.

bea.exe is Onslaught CE's game program; onslaught-ce.exe is the program to start.

In the game
- Main menu > Onslaught CE: About (version, licence and links), Updates (how updating works and how to turn
  the checks off), Record sessions, Report a problem, Coming soon / ideas, Bonus: Aquila Prototype,
  Bonus co-op: Defence A, Bonus co-op: Defence B, and Special Thanks. The game's Credits remain separate.
  Coming soon / ideas describes planned features and their limits; it does not start those features.
- Bonus: Aquila Prototype is the original playable-demo level (201). It returns to the main menu after the level.
  Bonus co-op: Defence A and B are two-player local split-screen defence maps (856 and 858) on this PC.
  Choose each player's Battle Engine on the Multiplayer start page; player 2 uses the second set of keys in
  Controller Options or a second gamepad. Plug in both gamepads before starting if using two.
  These bonus levels do not advance career progress at level end; other game paths can still save the live
  career and settings during play, including on pause/continue.
- Console: during an eligible solo level, press the grave key (`; left of 1 on a US keyboard), type help and
  press Enter. Esc or grave closes it; the game does not pause. It is unavailable in multiplayer, demos,
  recordings and replays.
- Options > Cheats: the game's own cheats as On/Off switches, kept in ce.ini so they apply to every career;
  the line under the list says what the highlighted one does:
  - Unlock all levels (original code TURKEY): every level opens in the level select
  - Unlock all goodies (MALLOY): every goodie opens on the Goodies page
  - Goodie hints (latête): the Goodies page shows how to unlock each goodie; while it is on, goodies
    cannot be opened
  - God mode option (Maladim): adds a God switch to Controller Options, in the pause menu (applies at once)
    and in Options (applies from the next level), for no damage and endless energy; turning the cheat off
    ends god mode. God mode set this way is kept in ce.ini, not in your careers.
  - Free camera (F key, Aurore): in a level, F lets you fly the camera; F again returns it
  These switches are off in recordings and replays. Typing a code into a career's name still works as in the
  original.
- Keyboard: held keys are released on focus loss, and delayed releases are repaired when possible. Typed
  characters come from key presses; letter and digit keys use their physical positions across layouts.
- Walker dodging (on the ground, not already dodging): with the default US keyboard, tap A then D for right,
  or D then A for left.
  Try releasing the first key before pressing the other. Aim for about 0.15 game seconds between presses:
  the default window is more than 0.1 and less than 0.2 game seconds. Too fast or slow will not dodge.
  If you remapped controls or use another layout, check left and right movement in Controller Options.
  The English tutorial can show a cue in eligible ordinary solo play; it is off in recordings and replays.
- Zoom: with default mouse bindings, wheel down zooms in and wheel up zooms out. In eligible ordinary play,
  the default gamepad's right bumper zooms in and left bumper out. Manual zoom works only with some weapons;
  some zoom while charging. Check Controller Options for changed bindings.
- Controllers: gamepad and flight-stick defaults cover menus, solo play and bonus co-op when joystick controls
  have not been customized. Other local multiplayer uses Controller Options. Only virtual devices were tested.
- Photo mode: F11 (or the console's photo command) hides the HUD and cockpit for pictures, and F12 saves a
  screenshot. Both work in single-player levels, but not while a session is recorded or replayed, in multiplayer,
  a network game or a demo. Tested on Linux; Windows testing of it is limited (see the release notes).
- Mods (experimental): on Linux, Onslaught CE can read replacement game files, such as textures, from mods in the
  mods folder of your user folder, named by a mods= line in ce.ini. Every file is checked against the mod's
  mod.json when the game starts, and a mod with any problem is not loaded (the log says why). There is no mod
  menu yet. On Windows mods are not active in this release: a mods= line is ignored and the log says so. See
  Mods (experimental) in the project README.
- A save that fails now says so: after the pause menu's Continue, the game's own save error message ("An error
  occurred during saving." in English, and in the language you chose) appears for a few seconds at the bottom of
  the screen, and after a language change in the front end it appears in the usual message box. The career you
  had is unchanged. Recordings and replays show neither.
- A quiet console: the developers' messages are hidden unless BEA_PORT_VERBOSE=1 is set.
- A log file for reports, onslaught-ce.log in your user folder, and session recording (both below).

Screen modes and widescreen
Video Options > Display mode offers Windowed or Fullscreen. Quit and restart for a saved choice to take effect;
the menu says if the choice could not be saved. An explicit -forcewindowed game argument takes priority.
The saved display-mode choice is ignored while recording or replaying.
By default, Onslaught CE starts at your desktop's resolution; a saved or explicit screen mode can change it.
Video Options lists your monitor's sizes, including widescreen ones. On a widescreen monitor the 3D view shows
more to the sides (the original's vertical view is kept). Menus, loading pictures and films keep their original
4:3 shape, centred with black bars, and the in-game HUD sits
where it would on a 4:3 screen. To get the original's 4:3-only list and 640 x 480 start back, set
BEA_PORT_WIDESCREEN=0. Replays and recordings always use the original 4:3 behaviour. The original game shares one
random number source between visual effects and play, so a wider view can change the details of a fight.
In eligible ordinary single-player play with widescreen modes enabled, the HUD automatically scales up when
both screen dimensions exceed 640 x 480. Set BEA_PORT_HUD_SCALE=0 for the original fixed-size HUD. Scaling is
off in recordings and replays, multiplayer, and when BEA_PORT_WIDESCREEN=0.
On a wide screen where the menus' and HUD's text is drawn at twice its original size or more (a 4K screen,
for example), Onslaught CE draws it from a sharper copy of the game's letters, so it stays crisp instead of
soft; the letters keep their shapes, sizes and places. The text is deliberately sharper than the original's
soft pixels, and looks brighter. A font's sharper copy is made the first time it is used, which can pause the
game for a moment (about a tenth of a second). This is off in recordings and replays, on 4:3 screens and when
BEA_PORT_WIDESCREEN=0.

Report a problem
Choose Onslaught CE > Report a problem in the main menu, or run onslaught-ce.exe --report (from a Command Prompt
in this folder, or a shortcut with --report added).
It opens a new issue on the project's GitHub page in your browser, filled in with your version and
system, and shows the folder that holds your log. Nothing is posted until you submit the issue. Say what
happened and how to make it happen again, and attach onslaught-ce.log from that folder
(%APPDATA%\Onslaught CE by default; onslaught-ce.old.log is the run before, and each stops at 4 MB). BEA_USER_DIR
can select another folder. The log holds
the version, your OS and GPU and the game's messages. Home paths and account-name path components are
shortened; look the file over before sharing it.
If you recorded the session (below), attach its tape too.

Help make Onslaught CE more faithful
We compare recorded input with the original; recordings of real play can reveal differences our tests miss.
Record one session with onslaught-ce.exe --record, or every session
with Onslaught CE > Record sessions in the main menu. That starts the next time you launch Onslaught CE
(quit the game, then start it again); it puts record_sessions=1 in ce.ini in your user folder.
While it is on, each start asks whether to record: Stop recording there, or starting with
onslaught-ce.exe --no-record, turns it off again.
By default, recording targets 30 frames a second for play and uses the replay clock. Its menus take
the keyboard and mouse, and you can type a career's name. Direct gamepad and flight-stick input is
disabled during recording and replay because the tape does not record it. An older tape made with live
controller input cannot recover it and may replay differently. The screen is the original 4:3.
The menus are the original's: the version text, no Onslaught CE menu and no Cheats page, and only cheats
typed into a career's name work. The larger HUD, console, CE tutorial dodge and zoom cues, and the saved display
mode are off; see Walker dodging above. By default the game tries to play sound through the audio monitor
when a device is available.
Each completed session is saved in the tapes folder beside ce.ini as a .tape and a .tape.json. The tape
records key presses and releases, typed text, mouse input, their frame numbers and the game's rendering
size for menu mouse input. The JSON includes version/build, platform/OS, date/time, clock, frame rate,
audio-monitor setting, game arguments and encoded copies of some CE user-folder files at the start,
including game options, careers and possibly other files. Session recording does not capture video, game
audio or microphone audio. Both files can contain personal information; review them before sharing.
To share a completed session, zip both files and say what differed from the original and roughly when.
An interrupted or failed capture may leave an .incomplete file; it is not a completed recording. Keep it
for diagnosis rather than replaying it.

Known limitations
- Windows builds have been checked under Wine on Linux and on one Windows 11 virtual machine with
  Microsoft's software renderer. Physical Windows graphics cards and drivers remain unvalidated for
  this version; see its release notes for the routes tested.
- The executables are unsigned, so SmartScreen may warn you (choose More info, then Run anyway).
- Complete tutorial parity with the original has not yet been established.
- Gamepad and flight-stick defaults cover menus, solo play and bonus co-op with uncustomized joystick
  controls. Only virtual devices have been tested; physical controllers and Windows drivers remain open.
- Physical audio devices and listening quality have not been validated by the recorded and virtual controls.
- Widescreen play is not compared with the original (the original has no widescreen); replays and recordings
  use 4:3.
- Planned, not in this version yet: Internet multiplayer, general mod support and additional HUD options.

Onslaught CE is an unofficial fan project. It is not affiliated with, endorsed by or sponsored by the owners of
Battle Engine Aquila or its publishers and developers. Battle Engine Aquila and related names and marks are
trademarks of their respective owners. No game files are included: Onslaught CE reads the player's own copy.

Licence: GPL-3.0-only (COPYING). Third-party components: THIRD-PARTY-NOTICES.txt and licenses/.
