README

   1 agsutils by rofl0r
   2 ==================
   3
   4 tools for (un)packing, disassembling, modifying and recompiling ags games.
   5
   6 agsex:
   7   runs agstract and agscriptxtract, then creates a Makefile with rules
   8   to quickly and automatically repack a pack with changed asm files.
   9   this basically does everything for you automatically.
  10   can also use `make optimize` to run agsoptimize on all asm files.
  11
  12 agstract:
  13   extracts the files a game "pack" (.exe) consists of.
  14   creates a file agspack.info which contains metadata about the
  15   files included in the pack.
  16   example:
  17
  18         agstract 252test.exe FILES
  19         :::AGStract 0.9.1 by rofl0r:::
  20         252test.exe: version 10, containing 6 files.
  21         ac2game.dta -> FILES/ac2game.dta
  22         acsprset.spr -> FILES/acsprset.spr
  23         agsfnt0.wfn -> FILES/agsfnt0.wfn
  24         agsfnt1.wfn -> FILES/agsfnt1.wfn
  25         agsfnt2.wfn -> FILES/agsfnt2.wfn
  26         room1.crm -> FILES/room1.crm
  27
  28   agstract can also extract speech.vox and audio.vox files.
  29   make sure to use a different output directory, otherwise your
  30   agspack.info will be overwritten.
  31
  32   in some games, speech.vox is insanely big because the speech files are
  33   saved in studio quality.
  34
  35   i achieved good results by converting them to 16Khz via ffmpeg:
  36
  37       for i in SPEECH/*.ogg ; do
  38         ffmpeg -i "$i" -c:a libvorbis -ar 16384 tmp.oga && mv tmp.oga "$i"
  39       done
  40
  41   then repacking it with agspack, which results in about 6x space improvement.
  42
  43   for audio.vox, you might want to use -b:a 80k instead of -ar 16384.
  44   this shrinks input files by about 400% with almost CD-like quality.
  45
  46 agspack:
  47   takes the files created by agstract and makes a new bundle out of it.
  48   example:
  49
  50         agspack FILES/ 252mytest.ags
  51         agspack -e FILES/ 252mytest.exe
  52
  53   without arguments, agspack produces a game pack missing the original
  54   windows exe stub, but is compatible with the opensource AGS engine,
  55   as well as with scummvm ags port.
  56   that way, a game is about 500 KB smaller after extract and repack than it
  57   originally was.
  58
  59   using the -e option, the original exestub is prepended to the game pack,
  60   and the offset to the start of the pack data encoded into the end signature,
  61   which reproduces the fully working windows executable with the new content.
  62
  63   note that agspack always produces a version 20/30 packfile, compatible only
  64   with ags 3.0 or newer, so if your exe stub is from an earlier game, it
  65   will fail to recognize the attached game data. in such a case you can
  66   use the exestub from a newer version, e.g.
  67   https://github.com/ags-archives/engines/blob/master/ags302sp1/acwin.exe
  68   save it as agspack.exestub in your extract directory.
  69
  70 agscriptxtract:
  71   detects and unpacks all binary scripts embedded in room and game files.
  72   the compiled scripts are stored with a .o extension, the disassembled files with .s.
  73   example:
  74
  75         mkdir OBJ ; cd OBJ
  76         agscriptxtract ../FILES
  77         disassembling globalscript.o -> globalscript.s
  78         disassembling room1.o -> room1.s
  79
  80 agsdisas:
  81   disassembles a single .o file to .s. useful to compare a re-assembled file with the original.
  82   example:
  83
  84         agsdisas room1.o room1.s
  85         disassembling room1.o -> room1.s
  86
  87 agssemble:
  88   creates a compiled object file from a .s assembly file.
  89   example:
  90
  91         agssemble room1.s
  92         creates a new room1.o (you will notice filesize/date has changed)
  93
  94   the compiled object file will miss unused strings and thus be smaller than the original.
  95   also imports and exports cover only really used ones.
  96
  97 agsinject:
  98   once you have recompiled an .o file with agssemble, you can inject it into the original
  99   container file (either a .crm room file or a game file like "ac2game.dta")
 100   example:
 101
 102         agsinject 0 OBJ/room1.o FILES/room1.crm
 103
 104         injects room1.o at the first found script (0) in room1.crm.
 105         rooms have only 1 script so you must always use 0.
 106         for ac2game.dta kinda gamefiles, the index is i.e. 0 for the globalscript,
 107         1 for the dialogscript (if one exists), otherwise 1 is the first gamescript, etc.
 108
 109   after you injected your .o file, the next thing you want to do is agspack it all up again.
 110   then you can test your changes in the ags engine.
 111
 112 agsprite:
 113   a tool to extract sprites from acsprset.spr files, and to create a new one
 114   from a directory full of extracted sprites. has several options to create
 115   smaller spritecache files than original, for example by converting all
 116   true-color images to high-color, which is almost impossible to differentiate
 117   visually.
 118   unfortunately ags saves a "uses alpha channel" flag for every sprite in a
 119   different file.
 120   if it was set, a picture converted from 32 to 16bit will become
 121   invisible, unless it is fixed with `agsalphahack` tool.
 122   after repacking a .spr file, a new sprindex.dat must be created and the old
 123   one replaced with it (if one existed). agsprite has an option for that too.
 124   optionally, the old sprindex.dat can simply be removed by commenting out the
 125   line with sprindex.dat in agspack.info and reducing the filecount by 1.
 126   at present, agsprite only creates and accepts TGA files.
 127   if you want to edit a sprite and your tool can't handle TGA format (unlikely),
 128   you can still convert the file into a format of your choice with e.g.
 129   imagemagick's `convert` tool, and then convert it back to TGA before creating
 130   a new sprite pack.
 131   run agsprite --help for usage information, and/or check the git log of
 132   agsprite.c to read a lot of detailed commit messages.
 133
 134 agsalphahack:
 135   a tool to remove alphachannel flags from gamefiles. can delete either all
 136   or a single specified sprite number's alpha channel flag. this tool is a
 137   supplement to agsprite.
 138
 139 agsalphainfo:
 140   a tool to print alphachannel information for each sprite.
 141
 142 agssim:
 143   a simple simulator for ags assembly instructions.
 144   run agssim --help for more info.
 145
 146 agsoptimize:
 147   a python script which is run on some .s asm files, detecting common inefficient
 148   patterns emitted by the AGS compiler, and replacing them with more efficient
 149   versions. using all preset optimization patterns, this improves speed of the
 150   CPU-heavy (because of a lots of scripts) game "Operation Forklift" by ~15-20%,
 151   which is almost identical to the number of asm statements it removes.
 152   another advantage is that the script files become smaller.
 153
 154 ascc:
 155   the original AGS script compiler with some tweaks to support more C features.
 156   it's pretty handy to generate assembly code to inject into scripts.
 157   since ascc is based on the original AGS sources and is written in C++, it's
 158   available in a different repository: https://github.com/rofl0r/ascc .
 159
 160
 161 compilation:
 162 ------------
 163
 164 after acquiration of a C compiler toolchain (optimally GCC) and GNU make
 165 (e.g. on ubuntu: `apt install build-essential`),
 166
 167 simply run `make`.
 168
 169 if you need any special CFLAGS, LDFLAGS etc put them into config.mak
 170 or append them to the make command, i.e. `make CFLAGS="-O2 -g"`
 171
 172 compilation on windos:
 173 ----------------------
 174
 175 mingw is not supported. it' s a half-baked PoS, which lacks a dozen or more of
 176 the POSIX APIs we require. worse than that, it even has *wrong* prototypes
 177 for some of them, for example it defines mkdir(char*), but the proper prototype
 178 is mkdir(char*, int), so we'd have to litter the code with #ifdefs and remove
 179 parts of the functionality to support it. that's not gonna happen.
 180
 181 use cygwin. with cygwin, every works just fine without *any* changes. you can
 182 even run `make` and it produces files with .exe extensions even though we don't
 183 have a rule for that anywhere. you only need to ship cygwin-1.dll together with
 184 the binaries.
 185
 186 NEW!!! agsutils can now also be compiled using [PellesC](http://www.smorgasbordet.com/pellesc/)
 187 (use [pellescc wrapper](https://github.com/rofl0r/pellescc) to build from Makefile).
 188
 189 alternatively you can use WSL/WSL2 and just use native linux compiler and the
 190 binaries inside the WSL environment.
 191
 192 third-party library requirements:
 193 ---------------------------------
 194 none. \o/
 195
 196 License:
 197 --------
 198 there is a tiny part of code left from the original AGS engine, about 150 LOC in CLib32.c.
 199 it is covered under the artistic license, see file header for details.
 200 all other code is (C) 2012-2019 rofl0r and licensed under the LGPL 2.1+ with the "NO C++"
 201 exception.
 202 the "NO C++" exception means that you are not allowed to convert the code into C++, but
 203 you can link it to C++ code.
 204