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 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)
* hold: expand your cargo bay to 35t for 400 credits (one-time upgrade only)
* 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 "hold", "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".

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.6:

* 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 (400 credits) and can only be
  done once from 20t to 35t (like in classic Elite)
* 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

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. Stable subversions tend to
have even numbers, testing subversions tend to have odd numbers. Also, 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.

- How large is awlite?

As of now, the entire game is contained in a single file with a little under
500 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.

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

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