Package: nutcracker
NUTCrackerTools for editing resources in SCUMM games.Features:Extract and Edit fonts for v5-v7 + HEExtract and Edit NUT fonts - v7-v8Extract and Replace SMUSH video framesCompress SMUSH videos (like scummvm-tools)Extract and Rebuild game resources - v5-v8 + HEExtract and Inject text strings - v5-v8 + HEExtract and Replace background and objects images - v5-v8 + HE (option to extract EGA backgrounds)Decompile V5 Scripts to Windex-like (SCUMM debugger fromhttps://quickandeasysoftware.net/monkey-island-2-talkie-prototype) syntaxResourcesExtract and rebuildSupported games: V5-V8, HEExtract game resources to patch files using:nutcracker sputm extract PATH/TO/GAME.000*ReplacePATH/TO/GAME.000to actual game index file (Usually ends with.000,.LA0or.HE0)This also creates XML-like filerpdump.xmlto show which files were extracted.Rebuild game resources from patches (using original resource as reference):nutcracker sputm build --ref PATH/TO/GAME.000 GAMEFontsSPUTM Font (CHARchunks)Supported games: V5-V7, HEExtract the fonts using:nutcracker sputm fonts_extract PATH/TO/GAME.000*ReplacePATH/TO/GAME.000to actual game index file (Usually ends with.000,.LA0or.HE0)fonts will be extracted as PNG images to directoryGAME/charsrelative to workdir.*ReplaceGAMEwith name of the game (e.g.ATLANTISif game index file isATLANTIS.000)Modify the font images with any image editor.Create patch files for the modified font:nutcracker sputm fonts_inject --ref PATH/TO/GAME.000 GAMERebuild game resourcesnutcracker sputm build --ref PATH/TO/GAME.000 GAMENUT FontsSupported games: V7-V8DecodingDecode all NUT files in given directory DATADIRnutcracker smush decode DATADIR/*.NUT --nut --target OUTDIRCreates a font image file named chars.png in OUTDIR which can be edited using regular image editing software (e.g. GIMP)EncodingEncode given font image (PNG_FILE) with given codec number (CODEC) using REF_NUT_FILE as referencepython -m nutcracker.smush.encode PNG_FILE --target NEW_NUT_FILE --ref REF_NUT_FILE --codec CODEC [--fake CODEC]This will convert font image file back to font file (NEW_NUT_FILE) which can be used in game.Available codecs:21 (FT + The Dig*)44 (COMI*)*FONT3.NUT and the fonts in The Dig was actually encoded using codec 21 method but marked as 44.
It can be achieved using--codec 21 --fake 44.
see examples intest.batSMUSH VideosDecode and Re-encodeSupported games: V7-V8Decode frames usingnutcracker smush decode DATADIR/*.SAN --target OUTDIRFrames will be extracted as PNG files toOUTDIR/VIDEO.SANwhereVIDEO.SANmatches the filename of the video.Re-encode the video using:python -m nutcracker.smush.encode_san_seq DATADIR/VIDEO.SANwhere DATADIR/VIDEO.SAN is path to original SMUSH video fileThe new video will be created asNEW_VIDEO2.SANin workdir*To reduce result file size, it is recommended to only re-encode modified frames, this can be done by removing unaltered frames fromOUTDIR/VIDEO.SANCompressSupported games: V7-V8Compress video frames using zlib compression, as in scummvm-toolsnutcracker smush compress DATADIR/*.SANTextExtract and Inject script textSupported games: V5-V8, HEExtract all texts from game to text file using:nutcracker sputm strings_extract --textfile strings.txt PATH/TO/GAME.000*ReplacePATH/TO/GAME.000to actual game index file (Usually ends with.000,.LA0or.HE0)Edit the text file using regular text editor.Inject the modified text in game resources using:nutcracker sputm strings_inject  --textfile strings.txt PATH/TO/GAME.000Decompile game scriptSupported games: V5Decompile game scripts to script file with Windex-like syntax:python -m nutcracker.sputm.windex_v5 PATH/TO/GAME.000*ReplacePATH/TO/GAME.000to actual game index file (Usually ends with.000,.LA0or.HE0)GraphicsRoom background and object imagesSupported games: V5-V8, HEExtract room background and object images using:nutcracker sputm room decode [--ega] PATH/TO/GAME.000*ReplacePATH/TO/GAME.000to actual game index file (Usually ends with.000,.LA0or.HE0)*Use the--egaif you wish to simulate EGA graphics on games with EGA backward compatibility mode, don't use it if you wish to modify the graphics for injecting modified graphics laterRoom backgrounds and Object images will be extracted as PNG images inGAME/backgroundsandGAME/objectsrespectively, whereGAMEis replaced with the name of the game.Modify the image files, it's recommended to use image editor without palette optimization, such as GraphicsGale.Create patch files for the modified images using:nutcracker sputm room encode --ref PATH/TO/GAME.000 GAMERebuild game resourcesnutcracker sputm build --ref PATH/TO/GAME.000 GAME