Tree [e8f792] /
History



File Date Author Commit
examples 2013-01-16 Jaka Kranjc Jaka Kranjc [3662b5] converted most prints to use the function syntax
infinity 2013-12-13 Jaroslav Benkovsky Jaroslav Benkovsky [e8f792] Have save_state() and restore_state() in builtins
.gitignore 2013-06-09 Jaka Kranjc Jaka Kranjc [8e2fca] gitignore: added for *.pyc
COPYING 2005-03-02 Jaroslav Benkovsky Jaroslav Benkovsky [42ca9f] Initial revision
Makefile 2009-01-29 Jaroslav Benkovsky Jaroslav Benkovsky [166202] Trying to merge iesh-infinity branch
README 2012-08-27 Jaroslav Benkovsky Jaroslav Benkovsky [7b2836] Expand shell and documentation a bit
TODO 2012-08-27 Jaroslav Benkovsky Jaroslav Benkovsky [7b2836] Expand shell and documentation a bit
bam_composer 2012-12-13 Jaroslav Benkovsky Jaroslav Benkovsky [82fd76] Add bam_composer script for assembling BAM images
examples.py 2008-02-27 Jaroslav Benkovsky Jaroslav Benkovsky [c14c3c] Moved things a bit
iediff 2010-07-26 Jaroslav Benkovsky Jaroslav Benkovsky [d9e472] Merge branch 'master' of ssh://gemrb.git.source...
ieparse.py 2013-01-16 Jaka Kranjc Jaka Kranjc [3662b5] converted most prints to use the function syntax
iesh 2013-12-13 Jaroslav Benkovsky Jaroslav Benkovsky [e8f792] Have save_state() and restore_state() in builtins
ieview.py 2013-01-16 Jaka Kranjc Jaka Kranjc [3662b5] converted most prints to use the function syntax
iezip 2009-08-28 Jaroslav Benkovsky Jaroslav Benkovsky [ccb340] Enhanced the iezip utility - more options, fixe...
mos2tis.py 2013-01-16 Jaka Kranjc Jaka Kranjc [3662b5] converted most prints to use the function syntax
setup.py 2009-01-29 Jaroslav Benkovsky Jaroslav Benkovsky [166202] Trying to merge iesh-infinity branch

Read Me

iesh - Python shell and package for exploring Infinity Engine-based data files
==============================================================================


Installation:
-------------
If you are installing from the source package, type

# python ./setup.py install

Package contents:
  iesh - simple Python interactive shell with history, tab completion, pager 
  infinity/ - python module package
  infinity/formats/*.py - modules for reading and writing specific IE file formats

  infinity/stream.py
  infinity/format.py
  infinity/core.py
  infinity/builtins.py
  
  data/ - directory for storing exported data, provided for convenience
  examples/ - some example code snippets



Running:
--------
iesh is a simple shell for execution of Python statements.
In fact, it's not that much different from ipython or even python's
built-in shell itself, it's just slightly tweaked to ease 
working with infinity package and you could easily use
the python package without it.

Key differences include:
 * readline to complete names in Python namespace
 * infinity.streams.*, infinity.formats.*, core and builtins.*
   modules or objects are imported
 * output is filtered through pager
 * commands prefixed with '!' are passed to shell
 * files prefixed with '@' are executed by iesh.
 * statements prefixed with '~' are run through python debugger
 * ?


To start iesh, just run ./iesh or python ./iesh and you
get to Cmd: prompt where you can type python statements.

Up and down arrows are used to browse command history, Ctrl-R
searches history for a command and TAB completes names of 
Python objects. See documentation for python readline module
for more information.

For some functionality it's needed to load game's RESREFs and STRREFs
- i.e. list of resources and strings in CHITIN.KEY and DIALOG.TLK
files. To load them, run load_game () function like this:

    Cmd: load_game ("/home/user/dos/bg2")

dots marking progress as the program loads CHITIN.KEY and DIALOG.TLK.

!!! This might take *extremely* long time on a slow computer and
a significant portion of memory. If it's too slow or too big, then
this proggie just is not for you :( !!! 

Once the files are loaded, you get Cmd: prompt, 
Now you can load files, inspect their contents, search them and export
objects out of them.

To considerably speed up the loading in the future, save a parsed representation
of the data objects:

    save("bg2")

And next time instead of load_game() just use:

    restore("bg2")


Common tasks:
-------------
To load and parse a file or object, use the load_object() function:

    o = load_object("data/STONEBIG.BAM")

or even:

    o = load_object("STONEBIG")
 
If the named file is not found at the given path, it's searched for in game's data, 
but that requires that game data were already loaded.
 
To print the content of the object you just loaded:

     o.printme()

Image file types can be viewed:

    o.view()

To write object back to disk:

    f = FileStream().open("data/tmp.tmp", "wb")
    o.write(f)
    f.close()

(But not all objects support that already)

To directly export an object to a file:

    export_object("STONEBIG", "data/tmp.tmp")  


Encoding support:
-----------------
To print strings from a foreign-language version of DIALOG.TLK, you have to set
encoding used by the game data and by your terminal.

For example, to print a string from the Korean version:

    core.set_option("format.tlk.encoding", "cp949")
    core.set_option("encoding", "utf8")
    o = load_object("data/dialog.tlk")
    print o.strref_list[1]['string']


Getting help:
-------------
?, help
help (object)
help (infinity)
help (infinity.builtins)
?object
...

Debugging
---------
~
format.debug_read
format.debug_write
stream.debug_coverage


Configuration:
--------------

  $HOME/.iesh_profile

game_dir 
    - directory where the game you are interested in is installed

chitin_file
dialog_file 
    - names of RESREF and STRREF index files, located in game_dir.
      Edit the names if the case does not match



The following resource formats are recognized in this version:
  2DA
  AREA V1.0
  BAM V1
  BAMC V1
  BIFF V1
  BIF V1.0
  CHUI V1
  CRE V1.2
  DLG V1.0
  IDS
  ITM V1.1
  KEY V1
  MOS V1
  MOSC V1
  PRO V1.0
  SPL V1
  STOR V1.1
  TIS V1
  TLK V1
  VVC V1.0
  WED V1.3
  WFX  V1.0
  WMAP V1.0

Type list_formats() to print list of recognized file formats.
  
Type `?' or `help' to get some online help and `q', `quit' or ^D
to exit the program.


Struc format:
-------------
Many of the *_Format classes used for processing IE files use
description of their respective file format specified as one or 
several *_desc lists. Each item in a list defines one data field, 
presumably a member of a struct originally used by IE to create
the file.

Each field is a dictionary whose items specify field's key,
offset, size, type and label, possibly more.

key - field name, used as a key in the resulting object
type - data type used to read, write and display the field
off - field offset, relative to struc's offset 0x0000
label - label printed for this field
enum - map of field values to their descriptions or IDS filename
mask - map of bit masks[FIXME: or bit nums?] to their descriptions
size - num of bytes for BYTES data type
count - count of fields of the same type and description


Other files:
  $HOME/.iesh_profile
  $HOME/.iesh_history
  $HOME/.iesh_save
  $HOME/.iesh_save-*


License, disclaimer and similar stuff:
--------------------------------------

Copyright (C) 2004 by Jaroslav Benkovsky, <edheldil@users.sf.net>

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.