scnhacking tool version 0.10 by [furrycat], 2008-05-18

This tool allows you to do cool stuff with SCN files.  It is not aimed at 
beginners.


Usage
-----
scnhacking [options] [filenames] [[options] [filenames]]


Arguments
---------
       --strip-lights
  -r,  --replace-colours
       --force-colours
       --add-attribute <entity> <key> <value>
  -s,  --search-entity <key> <value>
       --search-entity-id <entity>
       --search-entity-class <classname>
  -e,  --edit-attribute <entity> <key> <value>
       --delete-attribute <entity> <key>
  -ae, --add-entity <name> <classname> (NEW in 0.7)
  -de, --delete-entity <entity> (NEW in 0.7)
       --describe <feature>
  -D,  --describe all
  -d,  --debug
  -sd, --super-debug
  -v,  --verbose
  -q,  --quiet
  -o,  --outfile <filename>
       --prefix <prefix>
       --suffix <suffix>
  -V,  --version

The commands and their syntax ARE SUBJECT TO CHANGE!


Commands
--------
--strip-lights:
  Removes lightmaps from the SCN.
  If you don't know what this means, why this is good or what you are supposed 
  to do next (hint -blmaps -map ...), you don't need this option.

--replace-colours <light> <r> <g> <b>:
  Sets the RGB values for the Color attribute of the given light.  
  The light argument can either be a light ID (not the entity ID) or the 
  string "all" to process all lights in the map.
  The R, G and B values can each be specified in one of two ways.  Either a 
  floating point number between 0.0 and 1.0 or an integer between 0 and 255.  
  If scnhacking sees a decimal point it will assume you are using the floating 
  point format, otherwise it will divide the integer argument by 255 to obtain 
  a suitable floating point number.
  This command will almost certainly be changed in the future.
  This command was added in scnhacking version 0.2.

--force-colours:
  Some lights in the scene do not have a Color attribute.  In versions of 
  scnhacking prior to 0.3, the default behaviour was to create if it was 
  missing.  From 0.3 you must use --force-colours explicitly.
  This command was added in scnhacking version 0.3.

--search-entity <key> <value>:
  Finds entities with attributes matching key and value.
  You can use the empty string "" as value and scnhacking will find all 
  entities with the key attribute regardless of its value.
  This command can be used in conjunction with other entity search commands 
  (including multiple occurrences of itself) and scnhacking will display only 
  the entities which match all search criteria.
  For example, to find all cells where AIs must crouch you could use
    
    scnhacking --search-entity-class cell --search-entity mustcrouch 1

  This command was added in scnhacking version 0.6.

--search-entity-id <entity>:
  Finds the entity with given ID.
  This command can be used in conjunction with other entity search commands 
  and scnhacking will display only the entities which match all search criteria.
  This command was added in scnhacking version 0.6.

--search-entity-class <class>:
  Finds entities of type class.
  This command can be used in conjunction with other entity search commands 
  and scnhacking will display only the entities which match all search criteria.
  This command was added in scnhacking version 0.6.

--edit-attribute <entity> <key> <value>:
  Edits attributes for the given entity.
  You must specify the entity by ID as this is its only guaranteed unique 
  attribute.
  If key matches an existing attribute, the value of the attribute will be set 
  to value.  If there is no match, scnhacking will return an error.
  Beware that if an entity has two attributes of the same value, only the first 
  will be affected.  Use --delete-attribute first in this case to remove the 
  duplicate attribute.
  The command will return without error if the value of key is already value.
  Using --edit-attribute with a blank value (ie "") is the same as 
  --delete-attribute entity key.
  This command was added in scnhacking version 0.3.

--add-attribute <entity> <key> <value>:
  Adds a new attribute for the given entity.
  As with --edit-attribute, you must specify the entity by ID.
  The command will fail if an attribute with the given key name already 
  exists.  Use --delete-attribute first in this case to remove the 
  duplicate attribute.
  This command was added in scnhacking version 0.3.

--delete-attribute <entity> <key>:
  Deletes the attribute named key from the given entity.
  The command will return without error if no attribute with the given key i
  name exists.
  This command was added in scnhacking version 0.3.

--add-entity <name> <classname>:
  Adds a new named entity of the given class.
  This command was added in scnhacking version 0.7.

--delete-entity <entity>:
  Deletes the given entity (specified by ID).
  This command was added in scnhacking version 0.7.

--summary:
  Prints a summary of the SCN.
  This command was added in scnhacking version 0.4.

--describe <feature>:
  Prints a more detailed summary of a feature of the SCN.
  Use -D or "--describe all" to see all features.
  Use --describe without an argument to see the list of features you can 
  describe.

--outfile <filename>:
  Write the new SCN to <filename> instead of replacing the original.
  You are STRONGLY advised to make use of the --outfile option to save your 
  changes to a different file, thus preserving your original as backup!
  You can also use "--outfile -" to write the new SCN to standard output.

--prefix <prefix>:
  Adds the prefix <prefix> to the input filename and uses that in place of any 
  output filename.
  Use --prefix for batch conversion of many files.

--suffix <suffix>:
  Similar to --prefix.  For example: scnhacking --suffix .new *.SCN
  Use --suffix for batch conversion of many files.

--debug:
--verbose:
--super-verbose:
--quiet:
  Do what you would expect them to.  If you don't know what you should be 
  expecting them to do, read the gsmhacking documentation.


Command aliases
---------------
Many commands have various aliases that you can use instead of the default:

--strip-lights: --strip-lightmaps
--replace-colours: --replace-colour --replace-colors --replace-color
--force-colours: --force-colour --force-colors --force-color
--search-entity: --search-entities --search-entity-attribute 
                 --search-entities-attribute --search-entity-by-attribute
                 --search-entities-by-attribute
--search-entity-id: --search-entities-id --search-entity-by-id
                 --search-entities-by-id
--search-entity-class: --search-entities-class --search-entity-by-class
                 --search-entities-by-class
--add-attribute: --add-entity-attribute
--edit-attribute: --edit-entity-attribute
--delete-attribute: --delete-entity-attribute
--outfile: --output


Changes
-------
Changes from version 0.9:
  Compiler food.
Changes from version 0.8:
  --edit- attribute also didn't include the trailing null in fields.
Changes from version 0.7:
  --add-entity didn't included trailing null in fields.
  --add-attribute didn't either.
  Fixed potential buffer overrun in entity parser.
Changes from version 0.6:
  Added option --add-entity.
  Added option --delete-entity.
Changes from version 0.5:
  Option --describe now takes an argument.  Option -D is now synonymous with 
  --describe all.
  Added option --search-entity-attribute.  It claims the -s abbreviation.
  Added option --search-entity-class.
  Added option --search-entity-id.
  Fixed bug where the program would hang with more than one --replace-colours 
  argument.
Changes from version 0.4:
  We were using shorts instead of ints in some places.
  Fixed --edit-attribute (doh!).
  Summary and description now show number of each type of entity.
  Option --strip-lights can no longer be abbreviated to -s.
Changes from version 0.3:
  Fixed --delete-attribute.
  We weren't adjusting the header to account for changes in the entity data 
  stream length.
  Added some sanity checks to catch bogus files.
  Added new option --summary which is now the default behaviour.
Changes from version 0.2:
  Fixed a few memory leaks including one crashbug.
  Windows users now no longer have to use --outfile.
  Added option --force-colours and set default behaviour not to use it.
  Added option --add-attribute.
  Added option --edit-attribute.
  Added option --delete-attribute.
Changes from version 0.1:
  Removed redundant ``showmissing'' option left over from gsmhacking.
  Default behaviour is now option --strip-lights.
  Added option --replace-colours.
  Added default option --describe.
  Added debug options.


Credits
-------
Slippery Jim:
  Slippery Jim would like you to believe that I had no interest in SCN files 
  nor any desire to write a tool to edit them before he came along.  Eight 
  months down the line there is no point in my trying to convince anyone 
  otherwise.  What is certainly true is that until he proposed a definite need 
  for such a program, I hadn't thought it worthwhile to begin work on one.

  Necessity, they say, is the mother of invention.  For saying "Hey make this" 
  and providing the sample files needed to figure out how to do it, Slippery 
  Jim deserves thanks and credit.

AlienAbducter: 
  For wanting --add-entity and --delete-entity badly enough to make me think 
  about doing them.  It didn't take me long to remember why I hadn't done them 
  in the first place: there's a bit of work involved.


Licence
-------
This software is public domain.  You may do whatever you wish with it.
