awlite/README

awlite: POSIX AWK port of Text Elite
------------------------------------
This is a simple port of Text Elite game engine (version 1.5 written in C 
by Ian Bell) to POSIX AWK. It can run on any system that supports current AWK
language standard. Compared to the original TE 1.5, this port also introduces
numerous fixes, optimizations and further gameplay improvements.

== Running the game ==

The overall command for running awlite looks like this:

LC_ALL=C awk -f awlite.awk [-v NO_ALIEN_ITEMS=1] [-v CENSORED=1]

You can replace "awk" with "nawk", "busybox awk", "gawk --posix",
"mawk -W posix" etc depending on which AWK implementation you have.
Note that LC_ALL=C environment variable setting is **required** for all
implementations to work correctly and identically, although in practice
nawk and busybox awk might not need it.

Optionally, you can also supply these flags to change some game aspects:

* -v NO_ALIEN_ITEMS=1 forces "Alien Items" goods unavailability in the game;
* -v CENSORED=1 replaces "Slaves", "Narcotics" and "Liquors" goods names.

Of course, awlite is fully scriptable, e.g. you can append < script.txt to the
basic game launch command.

== In-game commands ==

As you launch a fresh game, you start on the planet Lave of Galaxy 1, 
on a Cobra Mk3 ship with 20t of cargo space, with 100 credits of cash.
From now on, the following commands are available (case-insensitive):

* buy (product) (amount): buy specified amount of specified product
* sell (product) (amount): sell specified amount of specified product
* fuel (amount): buy (amount) lightyears of fuel 
* jump (planetname): fly to planetname, deducing fuel accordingly
* galhyp: hyperspace jump to the next galaxy, deducing 5000 credits
  (8 galaxies total, you will jump from galaxy 8 back to galaxy 1)
* info [planetname]: print info on planetname, or current system if omitted
  (the planet must be in the same galaxy as you)
* mkt: show local planetary system market prices
* local: list planetary systems within 7 lightyears (your max fuel capacity)
* upgrade: expand your cargo bay by upgrading your ship or buying a new one
* stat: show player statistics and overall rank
* save (name): save the gamestate in the current working directory
* load (name): load the gamestate from the current working directory
* help: display an in-game command help screen
* rand: toggle between the AWK's native PRNG (default) and a custom one
* quit: quit the game

All commands except "upgrade", "save" and "load" can be abbreviated by their
first letter. In addition, trade goods names can be abbreviated too (by several
first letters). E.g. "b fo 5" is the same as "buy Food 5", and "q" is "quit".
The "upgrade" command can be abbreviated as "up".

Fuel price is fixed at 0.2 CR/LY, you can hold 7LY of fuel at most.

== Gameplay differences from the original TE 1.5 C version ==

As of the current version, 1.8.1:

* multiple typos corrected in text strings
* the "cash" and "sneak" commands were removed since v1.6
* galaxy jumps are no longer free and cost 5000 credits each
  (like in classic Elite and Oolite)
* cargo hold expansion also is non-free and (since v1.8) multi-tiered
* alien items are available by default
  (can be overridden with -v NO_ALIEN_ITEMS=1)
* economy names are no longer shortened
* the "politically correct" goods names are turned on with -v CENSORED=1
* the following goods have been renamed: "Robot Slaves" to "Robots",
  "Liquor/Wines" to "Liquors", "Gem-Strones" to "Gem-stones"
* market and local info tables are better aligned
* state saving/loading functionality introduced with "save"/"load" commands
* since v1.6.1, the game gives you a hint if you might have found Raxxla
* since v1.6.3, galaxy names are also displayed with "local" command
  (the names were taken from the Archimedes version of Classic Elite)
* since v1.7, basic ranking and statistics have been introduced
* since v1.8, "hold" command was replaced with "upgrade" with several ships

To be continued. This list is expected to grow in the future.

== FAQ ==

- What is Text Elite anyway?

Text Elite is a subset of the original Classic Elite for BBC Micro, first
implemented by Ian Bell in 1999, featuring trading only and text-based
interface. Quoting Ian Bell himself from his website:

> Text Elite is a C implementation of the classic Elite trading system
> in a text adventure style shell. I originally coded this to formalise
> and archive the definition of the Classic Elite Universe, but have released
> it, with sources, now that Christian Pinder has publicly reverse engineered
> BBC Disk Elite trading into C. 
> Text Elite is currently trading only. There is no risk of misjump, police,
> or pirate attack. 

As of now, the last published version of the original Text Elite is 1.5.
Its source code can be found here: http://www.elitehomepage.org/text/

- So, is this a one-to-one port of Bell's Text Elite?

No. Although the original C source code was used as a base, porting was done
by looking at *several* existing ports to understand the logic and basically
rewriting everything in AWK from scratch. Besides the "Goat Soup" description
code strings and trade goods data, no copy-pasting was done whatsoever, and on
top of that, all data had to be converted to use octal and decimal notations
instead of hexadecimal as POSIX AWK does not support hex literals.

- Why do awlite versions start from 1.5.1 then?

Because awlite is versioned in terms of functionality. A direct one-to-one
port would have the same 1.5 version, and every slight improvement adds a new
subversion, i.e. bumps the version number by 0.0.1, whereas every new command
set implementation bumps the version number by 0.1, indicating that it's no
longer fully command-to-command compatible with the previous one.
The first published awlite version was 1.5.8, meaning 8 minor improvements.

- If there are no combat missions, what are the goals in awlite?

Like the original Elite and Text Elite, awlite has no end-game goal. There are,
however, some milestones you can achieve even now, for instance:

* reaching the Elite trade rank (in v1.7+ - see below);
* reaching a certain amount of credits;
* collecting certain amounts of rare valuable items;
* visiting all planets in all galaxies (2048 total);
* finding Raxxla (v1.6.1+ will give you a hint when you might have done so).

As of now, player ranking system and statistics are in the works. The basic
system of stats and ranks was introduced in v1.7. It is loosely based upon the
Trade ranks of Elite Dangerous but the formula is fully unique to awlite.

- How are ranks calculated in awlite v1.7 and above?

To keep things simple, the formula currently only considers the current cash
balance and overall expenses to calculate the profit margin, then taking log2
of it. As of now, the following profit margin to rank mapping is in effect:

* Under 100%: Penniless
* 100% to 200%: Mostly Penniless
* 200% to 400%: Peddler
* 400% to 800%: Dealer
* 800% to 1600%: Merchant
* 1600% to 3200%: Broker
* 3200% to 6400%: Entrepreneur
* 6400% to 12800%: Tycoon
* 12800% and above: Elite

So, to reach Elite trade rank, you need to make 128 times more money than you
spend. This system might change in future versions, as it's not clear whether
or not this is possible at all.

- I found an awesome trade route in awlite. Can I use it in other Elite games?

As long as those games are based on the classic Elite universe with the same
basic algorithms, your routes should work there too. Of course, if you want to
use the same route in a non-text Elite game, then you must also consider other
difficulties such as police and pirate attacks.

- Is combat system ever going to be introduced in awlite?

Highly unlikely. One of the project goals is to keep it simple.

- Are there ship upgrades available in awlite?

Yes, since v1.8, awlite offers 5 upgrade tiers similar to Oolite trade ships:

* Cobra Mk3 Extended (35t, 400 CR) - like in the original Elite versions
* Python (100t, 200000 CR)
* Boa (125t, 450000 CR)
* Boa 2 (175t, 495000 CR)
* Anaconda (750t, 650000 CR)

You can list and select them with the "upgrade" (or "up") command.
Note that once you upgrade to a better ship, previous tiers become unavailable.

- How large is awlite?

As of now, the entire game is contained in a single file with a little under
550 SLOC of POSIX AWK code. Future functionality might increase the codebase
size, but one of the goals is to keep it under 1000 SLOC no matter what.

- Why AWK?

Because the current AWK gaming scene is rather poor (besides a handful of some
GAWK-specific games), and it is an interesting challenge to port such a title
to an environment requiring nothing except a bare kernel and BusyBox to play.

- Where do the save files go? How are they named?

Save files are named "[name].awlite", where "[name]" is the one you've entered
during the save command. If you don't specify the name, a file called ".awlite"
will be created. Save files are always silently overwritten, so be careful!
Saves always go to the current working directory, i.e. the directory you've run
the awlite.awk script from (which is not necessarily the one where it resides).
This is the only truly cross-platform way to implement this functionality.

- Why didn't you keep the cheating commands present in the original?

In version 1.5.8, the commands "sneak" and "cash" were there in a special
"cheat mode" to preserve backward compatibilty with some trading scripts
written for the original Text Elite versions. Once it was proven the scripts
won't work correctly anyway, the cheat mode was removed starting with awlite
v1.6. You can manipulate the savefiles to achieve the same functionality if
you really need to cheat.

- Why don't the scripts give the same results as for the original TE.EXE?

Even though the internal PRNG is the same, some operations might be compiled
differently. TBH no existing TE ports fully replicate these operations either.

- I want command history in your game REPL!

Use rlwrap (https://github.com/hanslub42/rlwrap), Luke. Most likely, it is
available as a package in your distro already. Just prepend rlwrap before
awk in the original game launch command.

- If Ian Bell ever releases Text Elite 1.6, will the changes be applied here?

Depends on the changes, but this is very unlikely to happen as the most recent
update to the original C code of Text Elite was in 2015.

== Credits ==

Original high-level algorithms from Text Elite 1.5 by Ian Bell, 1999, 2015.

Porting, corrections, improvements and optimizations by Luxferre, 2024.