awlite

POSIX AWK port of Text Elite game
git clone git://git.luxferre.top/awlite.git
Log | Files | Refs | README

README (10593B)


      1 awlite: POSIX AWK port of Text Elite
      2 ------------------------------------
      3 This is a simple port of Text Elite game engine (version 1.5 written in C 
      4 by Ian Bell) to POSIX AWK. It can run on any system that supports current AWK
      5 language standard. Compared to the original TE 1.5, this port also introduces
      6 numerous fixes, optimizations and further gameplay improvements.
      7 
      8 == Running the game ==
      9 
     10 The overall command for running awlite looks like this:
     11 
     12 LC_ALL=C awk -f awlite.awk [-v NO_ALIEN_ITEMS=1] [-v CENSORED=1]
     13 
     14 You can replace "awk" with "nawk", "busybox awk", "gawk --posix",
     15 "mawk -W posix" etc depending on which AWK implementation you have.
     16 Note that LC_ALL=C environment variable setting is **required** for all
     17 implementations to work correctly and identically, although in practice
     18 nawk and busybox awk might not need it.
     19 
     20 Optionally, you can also supply these flags to change some game aspects:
     21 
     22 * -v NO_ALIEN_ITEMS=1 forces "Alien Items" goods unavailability in the game;
     23 * -v CENSORED=1 replaces "Slaves", "Narcotics" and "Liquors" goods names.
     24 
     25 Of course, awlite is fully scriptable, e.g. you can append < script.txt to the
     26 basic game launch command.
     27 
     28 == In-game commands ==
     29 
     30 As you launch a fresh game, you start on the planet Lave of Galaxy 1, 
     31 on a Cobra Mk3 ship with 20t of cargo space, with 100 credits of cash.
     32 From now on, the following commands are available (case-insensitive):
     33 
     34 * buy (product) (amount): buy specified amount of specified product
     35 * sell (product) (amount): sell specified amount of specified product
     36 * fuel (amount): buy (amount) lightyears of fuel 
     37 * jump (planetname): fly to planetname, deducing fuel accordingly
     38 * galhyp: hyperspace jump to the next galaxy, deducing 5000 credits
     39   (8 galaxies total, you will jump from galaxy 8 back to galaxy 1)
     40 * info [planetname]: print info on planetname, or current system if omitted
     41   (the planet must be in the same galaxy as you)
     42 * mkt: show local planetary system market prices
     43 * local: list planetary systems within 7 lightyears (your max fuel capacity)
     44 * upgrade: expand your cargo bay by upgrading your ship or buying a new one
     45 * stat: show player statistics and overall rank
     46 * save (name): save the gamestate in the current working directory
     47 * load (name): load the gamestate from the current working directory
     48 * help: display an in-game command help screen
     49 * rand: toggle between the AWK's native PRNG (default) and a custom one
     50 * quit: quit the game
     51 
     52 All commands except "upgrade", "save" and "load" can be abbreviated by their
     53 first letter. In addition, trade goods names can be abbreviated too (by several
     54 first letters). E.g. "b fo 5" is the same as "buy Food 5", and "q" is "quit".
     55 The "upgrade" command can be abbreviated as "up".
     56 
     57 Fuel price is fixed at 0.2 CR/LY, you can hold 7LY of fuel at most.
     58 
     59 == Gameplay differences from the original TE 1.5 C version ==
     60 
     61 As of the current version, 1.8.1:
     62 
     63 * multiple typos corrected in text strings
     64 * the "cash" and "sneak" commands were removed since v1.6
     65 * galaxy jumps are no longer free and cost 5000 credits each
     66   (like in classic Elite and Oolite)
     67 * cargo hold expansion also is non-free and (since v1.8) multi-tiered
     68 * alien items are available by default
     69   (can be overridden with -v NO_ALIEN_ITEMS=1)
     70 * economy names are no longer shortened
     71 * the "politically correct" goods names are turned on with -v CENSORED=1
     72 * the following goods have been renamed: "Robot Slaves" to "Robots",
     73   "Liquor/Wines" to "Liquors", "Gem-Strones" to "Gem-stones"
     74 * market and local info tables are better aligned
     75 * state saving/loading functionality introduced with "save"/"load" commands
     76 * since v1.6.1, the game gives you a hint if you might have found Raxxla
     77 * since v1.6.3, galaxy names are also displayed with "local" command
     78   (the names were taken from the Archimedes version of Classic Elite)
     79 * since v1.7, basic ranking and statistics have been introduced
     80 * since v1.8, "hold" command was replaced with "upgrade" with several ships
     81 
     82 To be continued. This list is expected to grow in the future.
     83 
     84 == FAQ ==
     85 
     86 - What is Text Elite anyway?
     87 
     88 Text Elite is a subset of the original Classic Elite for BBC Micro, first
     89 implemented by Ian Bell in 1999, featuring trading only and text-based
     90 interface. Quoting Ian Bell himself from his website:
     91 
     92 > Text Elite is a C implementation of the classic Elite trading system
     93 > in a text adventure style shell. I originally coded this to formalise
     94 > and archive the definition of the Classic Elite Universe, but have released
     95 > it, with sources, now that Christian Pinder has publicly reverse engineered
     96 > BBC Disk Elite trading into C. 
     97 > Text Elite is currently trading only. There is no risk of misjump, police,
     98 > or pirate attack. 
     99 
    100 As of now, the last published version of the original Text Elite is 1.5.
    101 Its source code can be found here: http://www.elitehomepage.org/text/
    102 
    103 - So, is this a one-to-one port of Bell's Text Elite?
    104 
    105 No. Although the original C source code was used as a base, porting was done
    106 by looking at *several* existing ports to understand the logic and basically
    107 rewriting everything in AWK from scratch. Besides the "Goat Soup" description
    108 code strings and trade goods data, no copy-pasting was done whatsoever, and on
    109 top of that, all data had to be converted to use octal and decimal notations
    110 instead of hexadecimal as POSIX AWK does not support hex literals.
    111 
    112 - Why do awlite versions start from 1.5.1 then?
    113 
    114 Because awlite is versioned in terms of functionality. A direct one-to-one
    115 port would have the same 1.5 version, and every slight improvement adds a new
    116 subversion, i.e. bumps the version number by 0.0.1, whereas every new command
    117 set implementation bumps the version number by 0.1, indicating that it's no
    118 longer fully command-to-command compatible with the previous one.
    119 The first published awlite version was 1.5.8, meaning 8 minor improvements.
    120 
    121 - If there are no combat missions, what are the goals in awlite?
    122 
    123 Like the original Elite and Text Elite, awlite has no end-game goal. There are,
    124 however, some milestones you can achieve even now, for instance:
    125 
    126 * reaching the Elite trade rank (in v1.7+ - see below);
    127 * reaching a certain amount of credits;
    128 * collecting certain amounts of rare valuable items;
    129 * visiting all planets in all galaxies (2048 total);
    130 * finding Raxxla (v1.6.1+ will give you a hint when you might have done so).
    131 
    132 As of now, player ranking system and statistics are in the works. The basic
    133 system of stats and ranks was introduced in v1.7. It is loosely based upon the
    134 Trade ranks of Elite Dangerous but the formula is fully unique to awlite.
    135 
    136 - How are ranks calculated in awlite v1.7 and above?
    137 
    138 To keep things simple, the formula currently only considers the current cash
    139 balance and overall expenses to calculate the profit margin, then taking log2
    140 of it. As of now, the following profit margin to rank mapping is in effect:
    141 
    142 * Under 100%: Penniless
    143 * 100% to 200%: Mostly Penniless
    144 * 200% to 400%: Peddler
    145 * 400% to 800%: Dealer
    146 * 800% to 1600%: Merchant
    147 * 1600% to 3200%: Broker
    148 * 3200% to 6400%: Entrepreneur
    149 * 6400% to 12800%: Tycoon
    150 * 12800% and above: Elite
    151 
    152 So, to reach Elite trade rank, you need to make 128 times more money than you
    153 spend. This system might change in future versions, as it's not clear whether
    154 or not this is possible at all.
    155 
    156 - I found an awesome trade route in awlite. Can I use it in other Elite games?
    157 
    158 As long as those games are based on the classic Elite universe with the same
    159 basic algorithms, your routes should work there too. Of course, if you want to
    160 use the same route in a non-text Elite game, then you must also consider other
    161 difficulties such as police and pirate attacks.
    162 
    163 - Is combat system ever going to be introduced in awlite?
    164 
    165 Highly unlikely. One of the project goals is to keep it simple.
    166 
    167 - Are there ship upgrades available in awlite?
    168 
    169 Yes, since v1.8, awlite offers 5 upgrade tiers similar to Oolite trade ships:
    170 
    171 * Cobra Mk3 Extended (35t, 400 CR) - like in the original Elite versions
    172 * Python (100t, 200000 CR)
    173 * Boa (125t, 450000 CR)
    174 * Boa 2 (175t, 495000 CR)
    175 * Anaconda (750t, 650000 CR)
    176 
    177 You can list and select them with the "upgrade" (or "up") command.
    178 Note that once you upgrade to a better ship, previous tiers become unavailable.
    179 
    180 - How large is awlite?
    181 
    182 As of now, the entire game is contained in a single file with a little under
    183 550 SLOC of POSIX AWK code. Future functionality might increase the codebase
    184 size, but one of the goals is to keep it under 1000 SLOC no matter what.
    185 
    186 - Why AWK?
    187 
    188 Because the current AWK gaming scene is rather poor (besides a handful of some
    189 GAWK-specific games), and it is an interesting challenge to port such a title
    190 to an environment requiring nothing except a bare kernel and BusyBox to play.
    191 
    192 - Where do the save files go? How are they named?
    193 
    194 Save files are named "[name].awlite", where "[name]" is the one you've entered
    195 during the save command. If you don't specify the name, a file called ".awlite"
    196 will be created. Save files are always silently overwritten, so be careful!
    197 Saves always go to the current working directory, i.e. the directory you've run
    198 the awlite.awk script from (which is not necessarily the one where it resides).
    199 This is the only truly cross-platform way to implement this functionality.
    200 
    201 - Why didn't you keep the cheating commands present in the original?
    202 
    203 In version 1.5.8, the commands "sneak" and "cash" were there in a special
    204 "cheat mode" to preserve backward compatibilty with some trading scripts
    205 written for the original Text Elite versions. Once it was proven the scripts
    206 won't work correctly anyway, the cheat mode was removed starting with awlite
    207 v1.6. You can manipulate the savefiles to achieve the same functionality if
    208 you really need to cheat.
    209 
    210 - Why don't the scripts give the same results as for the original TE.EXE?
    211 
    212 Even though the internal PRNG is the same, some operations might be compiled
    213 differently. TBH no existing TE ports fully replicate these operations either.
    214 
    215 - I want command history in your game REPL!
    216 
    217 Use rlwrap (https://github.com/hanslub42/rlwrap), Luke. Most likely, it is
    218 available as a package in your distro already. Just prepend rlwrap before
    219 awk in the original game launch command.
    220 
    221 - If Ian Bell ever releases Text Elite 1.6, will the changes be applied here?
    222 
    223 Depends on the changes, but this is very unlikely to happen as the most recent
    224 update to the original C code of Text Elite was in 2015.
    225 
    226 == Credits ==
    227 
    228 Original high-level algorithms from Text Elite 1.5 by Ian Bell, 1999, 2015.
    229 
    230 Porting, corrections, improvements and optimizations by Luxferre, 2024.
    231