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.exe
  51
  52   the new "exe" will miss the original windows exe stub, but is
  53   compatible with the opensource AGS engine, as well as with scummvm ags port.
  54   that way, a game is about 500 KB smaller after extract and repack as it originally was.
  55
  56 agscriptxtract:
  57   detects and unpacks all binary scripts embedded in room and game files.
  58   the compiled scripts are stored with a .o extension, the disassembled files with .s.
  59   example:
  60
  61         mkdir OBJ ; cd OBJ
  62         agscriptxtract ../FILES
  63         disassembling globalscript.o -> globalscript.s
  64         disassembling room1.o -> room1.s
  65
  66 agsdisas:
  67   disassembles a single .o file to .s. useful to compare a re-assembled file with the original.
  68   example:
  69
  70         agsdisas room1.o room1.s
  71         disassembling room1.o -> room1.s
  72
  73 agssemble:
  74   creates a compiled object file from a .s assembly file.
  75   example:
  76
  77         agssemble room1.s
  78         creates a new room1.o (you will notice filesize/date has changed)
  79
  80   the compiled object file will miss unused strings and thus be smaller than the original.
  81   also imports and exports cover only really used ones.
  82
  83 agsinject:
  84   once you have recompiled an .o file with agssemble, you can inject it into the original
  85   container file (either a .crm room file or a game file like "ac2game.dta")
  86   example:
  87
  88         agsinject 0 OBJ/room1.o FILES/room1.crm
  89
  90         injects room1.o at the first found script (0) in room1.crm.
  91         rooms have only 1 script so you must always use 0.
  92         for ac2game.dta kinda gamefiles, the index is i.e. 0 for the globalscript,
  93         1 for the dialogscript (if one exists), otherwise 1 is the first gamescript, etc.
  94
  95   after you injected your .o file, the next thing you want to do is agspack it all up again.
  96   then you can test your changes in the ags engine.
  97
  98 agssim:
  99   a simple simulator for ags assembly instructions.
 100   run agssim --help for more info.
 101
 102 agsoptimize:
 103   a python script which is run on some .s asm files, detecting common inefficient
 104   patterns emitted by the AGS compiler, and replacing them with more efficient
 105   versions. using all preset optimization patterns, this improves speed of the
 106   CPU-heavy (because of a lots of scripts) game "Operation Forklift" by ~15-20%,
 107   which is almost identical to the number of asm statements it removes.
 108   another advantage is that the script files become smaller.
 109
 110
 111 compilation:
 112
 113 run `make`.
 114 if you need any special CFLAGS, LDFLAGS etc put them into config.mak
 115 or append them to the make command, i.e. `make CFLAGS="-O2 -g"`
 116
 117 License:
 118 there is a tiny part of code left from the original AGS engine, about 150 LOC in CLib32.c.
 119 it is covered under the artistic license, see file header for details.
 120 all other code is (C) 2012 rofl0r and licensed under the LGPL 2.1+ with the "NO C++"
 121 exception.
 122 the "NO C++" exception means that you are not allowed to convert the code into C++, but
 123 you can link it to C++ code.
 124