README

   1 agsutils by rofl0r
   2
   3 tools for (un)packing, disassembling, modifying and recompiling ags games.
   4
   5 agstract:
   6   extracts the files a game "pack" (.exe) consists of.
   7   creates a file agspack.info which contains metadata about the
   8   files included in the pack.
   9   example:
  10         mkdir 252test ; cd 252test
  11         agstract.out ~/srv/install/252test.exe .
  12         :::AGStract 0.0.1 by rofl0r:::
  13         ~/srv/install/252test.exe: version 10, containing 6 files.
  14         ac2game.dta -> ./ac2game.dta
  15         acsprset.spr -> ./acsprset.spr
  16         agsfnt0.wfn -> ./agsfnt0.wfn
  17         agsfnt1.wfn -> ./agsfnt1.wfn
  18         agsfnt2.wfn -> ./agsfnt2.wfn
  19         room1.crm -> ./room1.crm
  20
  21 agspack:
  22   takes the files created by agstract and makes a new bundle out of it.
  23   example:
  24         agspack.out . ../252mytest.exe
  25
  26   the new "exe" will miss the original windows exe stub, but is
  27   compatible with the opensource AGS engine, as well as with scummvm ags port.
  28   that way, a game is about 500 KB smaller after extract and repack as it originally was.
  29
  30 agscriptxtract:
  31   detects and unpacks all binary scripts embedded in room and game files.
  32   the compiled scripts are stored with a .o extension, the disassembled files with .s.
  33   example:
  34         agscriptxtract.out .
  35         disassembling globalscript.o -> globalscript.s
  36         disassembling room1.o -> room1.s
  37
  38   TODO: the room files of old versions contain the entire source code in encrypted form.
  39   we should extract it into a file room%d.c.
  40   see acroom.h at around line 2100.
  41         2125          for (hh = 0; hh < lee; hh++)
  42         (gdb)
  43         2126            rstruc->scripts[hh] += passwencstring[hh % 11];
  44         [...]
  45         2102      while (thisblock != BLOCKTYPE_EOF) {
  46         (gdb)
  47         2103        update_polled_stuff();
  48         (gdb)
  49         2104        thisblock = fgetc(opty);
  50         (gdb)
  51         2106        if (thisblock == BLOCKTYPE_EOF)
  52         (gdb)
  53         2109        fread(&bloklen, 4, 1, opty);
  54         (gdb)
  55         2110        bloklen += ftell(opty);  // make it the new position for after block read
  56         (gdb) p rstruc->scripts
  57         $8 = 0xa653b0 "// text script for room\r\n\r\nfunction internal_func() {\r\n  return 42;\r\n}\r\n\r\nfunction using_import() {\r\n\t int i = GetGlobalInt(1);\r\n\t i = i * internal_func();\r\n\t return i;\r\n}\r\n"
  58         (gdb) p bloklen
  59         $9 = 1002
  60
  61 agsdisas:
  62   disassembles a single .o file to .s. useful to compare a re-assembled file with the original.
  63   example:
  64         ../agsdisas.out room1.o room1.s
  65         disassembling room1.o -> room1.s
  66
  67 agssemble:
  68   creates a compiled object file from a .s assembly file.
  69   example:
  70         agssemble.out room1.s
  71         creates a new room1.o (you will notice filesize/date has changed)
  72
  73   the compiled object file will miss debug info (line numbers) and thus be smaller than the original.
  74   also imports cover only really used ones. it needs to be investigated whether this is compatible
  75   with the ags engine, but seemed to work in a quick test.
  76
  77 agsinject:
  78   once you have recompiled an .o file with agssemble, you can inject it into the original
  79   container file (either a .crm room file or a game file like "ac2game.dta")
  80   example:
  81         agsinject.out 0 room1.o room1.crm
  82
  83         injects room1.o at the first found script (0) in room1.crm.
  84         rooms have only 1 script so you must always use 0.
  85         for ac2game.dta kinda gamefiles, the index is i.e. 0 for the globalscript,
  86         1 for the dialogscript (if one exists), otherwise 1 is the first gamescript, etc.
  87
  88   after you injected your .o file, the next thing you want to do is agspack it all up again.
  89   then you can test your changes in the ags engine.
  90
  91
  92 compilation:
  93
  94 run `make`.
  95 if you need any special CFLAGS, LDFLAGS etc put them into config.mak
  96 or append them to the make command, i.e. `make CFLAGS="-O2 -g"`
  97
  98 License:
  99 there is a tiny part of code left from the original AGS engine, about 150 LOC in CLib32.c.
 100 it is covered under the artistic license, see file header for details.
 101 all other code is (C) 2012 rofl0r and licensed under the LGPL 2.1+ with the "NO C++"
 102 exception.
 103 the "NO C++" exception means that you are not allowed to convert the code into C++, but
 104 you can link it to C++ code.
 105