MTS has all free content, all the time. Find out how YOU can help to keep it running. Tell me how...

Postal Package Editor (and API)

by Echo Posted 9th Aug 2009 at 4:27 PM - Updated 27th Nov 2013 at 4:14 PM by Nysha
176 Comments / replies (Who?) - 24 Feedback Posts
Postal is a DBPF3 package editor. That means that it can open up Sims 3 package files, let you poke at their innards, change things around, then save them back into new package files.

Can I run it?
Postal is built on top of Java 6, so if you can run Java 6 then the answer is "yes". That includes Windows XP, Vista and Mac OSX. If you can run the Sims 3, you should be able to run this.
There is one caveat though. Because I'm running Windows, I cannot test well on Mac. Please let me know if you experience any issues.

What can it do?
Postal can navigate all kinds of Sims 3 package files, and parse/display/write many resources, including OBJDs, OBJKs, STBLs, XMLs, CSTRs, GEOMs, NMAPs, DDSs, PNGs, VPXYs, Texture Compositors and the various text-based formats. As time goes on, the number of resource types it can edit is growing.

Postal also has a filetable which keeps track of all the resources that can be used in game. You can use this to search for resources by type, group, or instance, wherever they come from. Postal has a scripting console, and a plugin architecture to allow you to add your own functionality to the application.

The Postal API
The Postal Editor is built on top of the "Postal API". This is a library which speeds up the process of writing custom tools which can read from and write to package files and the resource types inside them. The API is available under a BSD license, which essentially means you can use it however you like in your own tools as long as you acknowledge the original creator and point to a place where the original source can be downloaded. (The full Postal GUI is available under a GPL license)

The Postal API has already been used in other tools, including The Sims 3 Mod Generator and Merlin . There is some documentation on how to use it to build your own applications and how to extend the Postal environment attached.

INSTALLATION INSTRUCTIONS
- Go to http://www.java.com/en/download/manual.jsp and install the up-to-date version of Java for your operating system (if you don't already have it)
- Download the latest version of the Postal installer from http://sourceforge.net/projects/postal-sims3
- Double click on the file you have downloaded, and follow the Wizard. Make sure you put in the correct path to your Sims 3 installation when it prompts you!

* Mac OSX users, please see this post regarding running Java 6

Additional Credits:
Most of the behaviour here is based directly off the wiki pages describing file formats and resource structures. Thanks to Rick, Karybdis, Delphy, WesHowe, Inge, Peter, Atavera, Pescado and the many others who have contributed their knowledge to that collective effort.
Tags: #Postal, #DBPF, #editor, #api, #stbl, #dds, #geom, #xml

Operating System: Windows Linux Mac OS X
Utility Type: CC Editors
Plugin Type: Not Applicable

You must have the expansion or stuff packs listed below installed to use this custom content. Please see the post text for any exceptions.

Sims 3
Key: - File was updated after upload was posted
Filename - Tip: You can click the magnifying glass to see the archive contents Size Downloads Date
user-installation.rar | Install instructions (same as in post)

Size: 388 Bytes · Downloads: 21,158 · 10th Aug 2009
388 Bytes 21,158 10th Aug 2009
FOR-DEVELOPERS-ONLY-Postal-developer-guide-PDF.rar | Documentation for developers interested in using Postal in their own tools

Size: 308.1 KB · Downloads: 10,152 · 10th Aug 2009
308.1 KB 10,152 10th Aug 2009
Don't forget to Thank the creator after downloading! Use the Thanks button located above the screenshots above.
Quick Guide:

1. Click the file listed on the Files tab to download the file to your computer.
2. Extract the zip, rar, or 7z file. Now you will have either a .package or a .sims3pack file.

For Package files:

1. Cut and paste the file into your Documents\Electronic Arts\The Sims 3\Mods\Packages folder. If you do not already have this folder, you should read the full guide to Package files first: Sims 3:Installing Package Fileswiki, so you can make sure your game is fully patched and you have the correct Resource.cfg file.
2. Run the game, and find your content where the creator said it would be (build mode, buy mode, Create-a-Sim, etc.).

For Sims3Pack files:

1. Cut and paste it into your Documents\Electronic Arts\The Sims 3\Downloads folder. If you do not have this folder yet, it is recommended that you open the game and then close it again so that this folder will be automatically created. Then you can place the .sims3pack into your Downloads folder.
2. Load the game's Launcher, and click on the Downloads tab. Find the item in the list and tick the box beside it. Then press the Install button below the list.
3. Wait for the installer to load, and it will install the content to the game. You will get a message letting you know when it's done.
4. Run the game, and find your content where the creator said it would be (build mode, buy mode, Create-a-Sim, etc.).


Extracting from RAR, ZIP, or 7z: You will need a special program for this. For Windows, we recommend 7-Zip and for Mac OSX, we recommend Keka. Both are free and safe to use.


Need more help?

If you need more info, see:
 
176 Comments / Replies (Who?) - 155 Feedback Posts, 10 Thanks Posts
Hide Thanks Posts for this thread (Show only feedback)
Page 6 of 8
Pettifogging Legalist!
retired moderator
#126 Old 19th Feb 2010 at 1:06 PM Last edited by plasticbox : 19th Feb 2010 at 1:24 PM.
Quote:
Originally Posted by Echo
There, er, isn't an about box as far as I know...

There, er, is =P -- but if you didn't put it there, perhaps it's provided by the OS? See screenshots. I have no idea how this works in detail, but every OS X app has the menu shown on the first pic, with standard functions like About, Hide, Quit .. maybe the version in the About box is the Java version or something like that?

(I realise you have no influence over what OS X does =) – the pics are just fyi. If this menu is system-generated, that would also explain the duplicate "Quit" that I'm seeing, I believe I posted about that before)


Another thing: would it be possible to put up some sort of progress bar or busy cursor when Postal needs to dig around in the game files for a while? I just force quit it a couple of times thinking it's hanging or has crashed, but at some point I just left it open and did somehting else .. and when I came back it displayed an XML from the game files (a material reskey), so I guess that's what was taking so long. I realise those packages are 2GB each, so it's not surprising that it takes a while .. but it would be good if there was some indication that things are happening. It's not obvious to the user that when double-clicking one of the TGI entires it'll actually go and open them (I was looking at an OBJD).
Screenshots

Stuff for TS2 · TS3 · TS4 | Please do not PM me with technical questions – we have Create forums for that.

In the kingdom of the blind, do as the Romans do.
Retired Duck
retired moderator
Original Poster
#127 Old 20th Feb 2010 at 6:09 AM
Hee

Well that entire menu is a surprise to me - when I run it, I get "File", "Plugin" and "Workspace"... So that's a macism.

The slowness, is this happening just the first time you go to open a file, or every time. When it first goes rifling through the game files, it should be bringing up a progress bar, letting you know which files it's hunting about in and an expected duration. After that, it shouldn't take more than a second to get any resource from any package, since it holds a database of the exact offsets into the files for all the resources it knows about.

Some resources just take a long time to parse - STBLs, for example, can be quite big. But you shouldn't be waiting longer than 2 seconds for anything. It also doesn't load resources from any other files unless you specifically click on something like a TGI reference *inside* a resource.

Do you remember which OBJD you were looking at when you had the problem?
Pettifogging Legalist!
retired moderator
#128 Old 20th Feb 2010 at 2:09 PM Last edited by plasticbox : 20th Feb 2010 at 3:10 PM.
Re. "slowness"/inresponsiveness: I do get the progress bar the first time it loads the game files, but not after that. I was clicking on the TGI blocks of material blocks, where game resources are referenced – I'm pretty sure the one yesterday must have been one of the many versions of a custom chair I made, but this has been happening before with other objects too .. maybe I'm terminally impatient, but I always killed the process and went to open it on the Windows box instead.

It's not slowness *per se* that is the issue – just that there's no indication that it's doing anything. I'm pretty sure if I'd time it, it would turn out Postal is much faster than S3PE (it's running on a 2.4GHz machine after all, 4GB RAM, while S3PE is on a historical Windows box that in general acts like an elderly lame duck).



Another thing – can you tell from this whether the export from Hex view is working like it should?: when I open userPresets.package in Postal (which is a plain XML resource, it holds colour/material options for CASTable stuff), and export from the Hex view, the resulting file is a bit funny. I can open and view it in BBEdit but in order to make it readable for the Windows "Editor" I need to "zap gremlins" first (remove control characters and non-ASCII) and then save as Unicode. I'm not sure if that's normal, or if something becomes garbled (maybe due to the fact I'm on OS X?) – I was thinking a Hex dump would have to be ASCII since it contains nothing but 0-F, but these are .. something else. Is this normal?

e: screenshot with gremlins attached

It's not a problem really, since all I want to do with these is read stuff, but I guess it would be difficult to reimport them (I don't have an "insert gremlins" function =P).

e2: also, hmmmmmm .. wouldn't this have to be TWO zeroes there? See the other screenshot, looking at the same file in Postal. Every other digit byte? thing? is one "0".

e3: i also can't open these as utf-8, since they're "damaged or malformed". utf-16 in all flavors gives me no such complaints, but doesn't result in a very useful-looking file either ..


e4: i also found the docs about that surpise menu, in case you want to know: http://developer.apple.com/mac/libr.../uid/TP40001909 "Any Java application that uses AWT/Swing or is packaged in a double-clickable application bundle is automatically launched with an application menu similar to native applications in Mac OS X. This application menu, by default, contains the full name of the main class as the title. This name can be changed using the -Xdock:name command-line property, or it can be set in the information property list file for your application as the CFBundleName value. For more on Info.plist files, see “A Java Application’s Information Property List File.” " (I do realise that your OS X user base is probably like three people =)


e5: another suggestion (that is hopefully easy) – I just realised it would be nice if it displayed the total count of resources in a package somewhere. I just had to compare a few different versions of something, where I had only added/removed a few resources, and it would have been helpful to see the total count at one glance.
Screenshots

Stuff for TS2 · TS3 · TS4 | Please do not PM me with technical questions – we have Create forums for that.

In the kingdom of the blind, do as the Romans do.
Retired Duck
retired moderator
Original Poster
#129 Old 21st Feb 2010 at 10:00 AM
pb, I'm about to go out so I'll respond to the rest tomorrow, but the xml one I can answer right now. Most of the unicode xml files in .package files come with a jaunty little header which marks the file type and run length. Have you got a hex editor? If so, open up the exported package, delete the first 8 bytes (ie, the first two integers) then open it as file type "UTF-16LE". That should cover most of them.

If you want to import over the top again, you'll need to put these pieces back. The first four bytes should stay the same as they were in the original. The second integer (bytes 4 through 8) should be the number of characters to in the file (ie, the byte-length of the file, divided by 2).
Pettifogging Legalist!
retired moderator
#130 Old 24th Feb 2010 at 3:26 PM
Thanks for the info, echo. I have a hex editor; I'll try opening it like you said the next time I do this.

Stuff for TS2 · TS3 · TS4 | Please do not PM me with technical questions – we have Create forums for that.

In the kingdom of the blind, do as the Romans do.
Pettifogging Legalist!
retired moderator
#131 Old 1st Mar 2010 at 7:03 PM Last edited by plasticbox : 1st Mar 2010 at 7:18 PM.
I just saw that when looking at ObjectThumbnails.package, several resources will show up as UNK 0xad366f95 or 0xad366f96 or 0x0589dc47, but when I change them to 0x0580a2b5 or 0x0580a2b6 (PNG) and commit, they show up fine as PNGs. From what I've seen so far, ththe UNK ones all seem to be either "mobile" objects, like a seed (was 0xad366f95), a plate with a sandwich (was 0xad366f96); or wallpaper textures (was 0x0589dc47).

It doesn't seem to make a difference whether I change them to 0x0580a2b5 or 0x0580a2b6, both show up as PNG. The ones that are already considered PNG are all 0x0580a2b5 or 0x0580a2b6 – I can't see a pattern as to what the difference is). I don't know too much about the PNG format though, no idea about the finer differences (colour depth? size? alpha? byte order somethingorother?).

So yeah – would you be able to use a PNG preview for these things by default (or is there a reason you don't?)? That would make it much easier to see what is what.



Oh, and re. the XML thing: I've meanwhile seen that this particular resource (userPresets.package, in Documents) looks just as garbled in s3pe, with lots and lots of <NUL> characters that are in no other XML (those in the actual game resources look neat). I'm beginning to think that this is the game writing out garbage … possibly because it's writing to a file in a non-Windows environment? It wouldn't be the first time that EA can't handle that (and there are still encoding issues aplenty between Windows and *nix). OS, game, Postal, and text editor are all en-US so i guess that rules out actual language problems.

Stuff for TS2 · TS3 · TS4 | Please do not PM me with technical questions – we have Create forums for that.

In the kingdom of the blind, do as the Romans do.
Test Subject
#132 Old 12th Mar 2010 at 4:38 AM
Hi, I've read through this entire thread twice to make sure I haven't missed it. And I am sorry for posting with such a basic question. I run sims 3 on Mac OS X (v. 10.5.8) recently have gotten into downloading package files for my game. Mostly just objects, CAS stuff, and simple mods like sliders and the food overhaul one. Something like 130 in all, and now Buy mode is extremely laggy and slow. I just want to design houses, and have spent days trying to make sense of S3PE (only to discover it is near impossible to run on a mac). I was about to give up and borrow a friends old HP laptop for the Windows box method, till I saw in the comments on plasticbox's article a note about Postal. I've got it working (well opening at least, console as well), I just don't know how to use it. All I want to do is merge my package files into a few larger files because it seems like that is the thing to do. I've tried messing around with opening the packages in Postal, I just figured you could open a bunch at the same time (then save it as a new package), but this doesn't appear to be an option.

Am I missing something? A guide, or import button/tab or something? I feel like a literal baby when it comes to this stuff, especially when I know that what I want to do is so low on the food chain (or... complexity chain). Any input would be greatly appreciated.

Thank you so much, Echo, for creating this program, I hope I can master it soon. And thank you plasticbox for your solutions for os x users article, and continued input. You two make a good team.
Lab Assistant
#133 Old 30th Apr 2010 at 12:10 AM Last edited by groovilicious : 13th May 2010 at 6:32 PM.
Default Can I use this tool to re-categorize some patterns?
I downloaded some patterns from a Russian site, and there's a bunch of printy things in the paint category that should be in fabrics... In general I just have a lot of patterns I'd like to move to other categories. So... I opened up one of the downloaded patterns with Postal, and I can definitely see all those innards! Is it possible for me to change the catalog category where these patterns appear in game with this tool, and if so, how do I do that?!?
Thank you Echo for all your time and contributions to the community! I appreciate you!!

Edit to Add: Hugelunatic has done a tutorial on this that I missed, and she graciously pointed me to. Find it here:
http://www.modthesims.info/showthread.php?t=363669
Test Subject
#134 Old 6th Jun 2010 at 11:25 PM
Is this compatible with all the Ambitions changes?
Especially the Script/Core mod format changes.
Retired Duck
retired moderator
Original Poster
#135 Old 7th Jun 2010 at 2:56 AM
Kaldir,

Postal doesn't decode script files, so they are unlikely to cause an issue. I don't have Ambitions myself, so I cannot say whether there are any other files with problems, but I haven't heard about any other file format changes which would affect it.

Echo
Test Subject
#136 Old 7th Jun 2010 at 4:34 PM Last edited by KittyRobbie : 7th Jun 2010 at 6:25 PM. Reason: spalling and gremmer is impurtant
Thanks so much for this! I can't do any of the fancy moddy stuff with it, cos I'm dense, but I wanted a way to preview my custom content before I load it back into my game after my Ambitions install (to sort through the crap I'm not using), instead of my previous method of "move one custom item over, start game, search through buy/build/CAS until I find it, decide it's crap, delete, close game, repeat."
Test Subject
#137 Old 25th Jun 2010 at 12:21 AM
I can't get it to start. I've updated Java, then downloaded and installed through the .exe
I specified my default install folder for TS3. But when I try to run the program it just sits there. No errors. Nothing
I'm not familiar with java at all but would like to check out this program.
I'm running Win. XP 64x

Most of the questions I see are Mac OS installations so I'm sorry if this has already been answered.
Retired Duck
retired moderator
Original Poster
#138 Old 25th Jun 2010 at 2:24 AM
mchick, can you try running the "(debug mode)" version, and tell me if you get any errors? Also, could you post a screen shot of what you see?

Thanks!
Test Subject
#139 Old 25th Jun 2010 at 3:21 AM
Quote:
Originally Posted by Echo
mchick, can you try running the "(debug mode)" version, and tell me if you get any errors? Also, could you post a screen shot of what you see?

Thanks!


Thank you for the quick reply.
I run in debug mode and a blank command prompt screen comes up for about a split second and that's it.

It goes by so fast that I can't get a screen shot of it. Other than that, I have no other errors or anything to take a screeny of.

I am getting a windows error noise though when I try to run it.
Retired Duck
retired moderator
Original Poster
#140 Old 26th Jun 2010 at 7:04 AM
Okay, that sounds like there's a problem finding the Java program.

Can you try something else for me? Go to your Start menu, and choose "Run". In the box which shows up, type:
cmd
and click OK.
That will bring up a black box. Into that, type:
java -version
and then press Enter. Tell me what it prints back to you.

Then type:
exit
to close that window.
Test Subject
#141 Old 26th Jun 2010 at 3:30 PM
This is what it prints back to me:

java version "1.6.0_20"
jave SE runtime environment <build 1.6.0_20-b02>
java hotspot client vm <build 16.3-b01>
Retired Duck
retired moderator
Original Poster
#142 Old 27th Jun 2010 at 1:40 PM
Okay, I was expecting an error with that! In that case...

Do the "Run", "cmd", "OK" thing again to get a black console window, then type the following:
cd C:\Program Files\Postal
java -Xmx1024m -jar Postal-debug.exe
Test Subject
#143 Old 28th Jun 2010 at 3:24 AM
Okay, after entering that, I get:

"Error occurred during initialization of VM
Could not reserve enough space for object heap
Could not create the Java virtual machine"

Okay, now it's going way past what I can understand lol
Retired Duck
retired moderator
Original Poster
#144 Old 28th Jun 2010 at 3:37 AM
It saying you don't have enough memory available. How much memory does your machine have?

Try this instead of the last line:
java -Xmx512m -jar Postal-debug.exe
Test Subject
#145 Old 28th Jun 2010 at 4:03 PM
I thought that's what it meant, I have 2 GB of memory though.

But after typing that last line, it finally opened. Is that how I'll have to start the program up for now?
Retired Duck
retired moderator
Original Poster
#146 Old 29th Jun 2010 at 2:00 AM
Because Windows 64 bit takes 1gb of RAM just to start, and Postal can use up to 1gb of memory to store its file table information, you probably are running out.

You can try starting it up that way for now, but you'll probably get errors any time it tries to search for resources in the file table. The command I gave you starts up the program with only half its required memory, so you should be able to open up packages and look at stuff inside them, but you won't be able to follow connections between resources or search for files without it either hanging or shutting down...

You can probably make it work a bit better by taking out some of the resources in the file table though, depending on what kind of modding you're planning on doing.
Test Subject
#147 Old 29th Jun 2010 at 4:32 PM
You know, I just looked and I don't think I'm running a 64 bit.

After reading your answer, I thought 2 GB would be quite low for a 64x especially with the games I play on this computer requiring at least 1 GB (if not more).
So my properties don't say 64x or 32x anywhere, I imagine I'm running a 32x.
Sorry about giving you the wrong stats.

I probably won't be doing any heavy modding though. I actually just wanted to check out the program in connection with recoloring custom meshes using CTU.

Thanks for helping, quite appreciate it
Lab Assistant
#148 Old 10th Jul 2010 at 7:28 PM
Is there a manual of some sort for this program? What I am trying to do is delete a custom hair in the game that I probably have installed as a package file. The hair isn't showing up properly. Someone recommended I use this program to figure out which is the file I want to delete.

BREAKING NEWS! Toilet stolen from police station. The cops have nothing to go on.
Lab Assistant
#149 Old 29th Aug 2010 at 5:42 PM
How bizarre but I would swear I have systematically tromped through every single download page for sim3 stuff at this site recently, yet once again if something isn't posted at an update site somehow I'll miss it. Okay, I'm just using this for the thumbnail capability. THANK YOU Echo!!
Lab Assistant
DELETED POST
29th Aug 2010 at 6:39 PM
This message has been deleted by coffeebreak. Reason: redownloaded and works find thanks again
Page 6 of 8