Editing EffDir Files To Show Puzzle Piece Preview Models

[Tarkus]

Editing EffDir Files To Show Puzzle Piece Preview Models

Preview Models are a crucial aspect of making Puzzle Pieces.  They allow the user to see where the piece will be placed before actually placing it, and without them, the positioning of these pieces would be complete guesswork. 

In order to make a Preview Model appear, one must edit a type of file known as an Effects Directory, or EffDir for short.

A lot of times, there is some confusion as to what exactly this file is, as there is a lot of mention of "the Effects Directory", as if it were a singular file.  There is one main EffDir that controls all the effects in the game, and is what gizmo28 edited to produce his popular Day-Night Mod.  (If you're looking for a tutorial on that file, there isn't one--it's so large, it's still being deciphered.)  However, there are numerous other, small EffDir files which are used for defining preview models, which is what we will focus on in this tutorial.  These EffDirs will generally have the same Instance ID (IID) as the "AutoTileBase" defined for the piece in RUL 0x10000000 (corresponding to the "top-left corner" of the puzzle piece in most circumstances). 

Note: The actual S3D Preview Model will usually have a different IID than the AutoTileBase--most often, it will either be the AutoTileBase with the last "0" changed to "5" (0x5NNNNNN0 becomes 0x5NNNNNN5).

In the Reader, when highlighting an EffDir file, you may notice a dialog box open up on the right, as happens with just about every file.  Normally, to edit most files in the Reader, one would utilize the options presented there.  While it may look like you can edit EffDirs in this same way, upon changing the values in the boxes in this dialog box, they immediately revert back to their original values.  So how do you edit an EffDir?

You'll need to get into the Reader's Hex Editor.  In order to do so, simply right-click the EffDir you want to edit, and a menu will appear.  Select "Hex Editor (decoded file)".



You'll want to widen the view here, so just move the little slider at the top over to the right, and it will stretch the values out.



Now for the fun part.  See the number circled in red?  That is a reference to the IID of the Preview Model.  In this case, the IID of the Preview Model is 0x5CA01405.  In EffDir files, the IID is expressed backwards in 1-byte (2 character) chunks.  So, 5CA01405 becomes 05 14 A0 5C in the EffDir.



The IID reference occurs at two spots in the EffDir.  The first is in Line C0 (assuming you've stretched the view out as advised above), and the second is toward the end of Line 270. 

Here's a look at the second reference:



The last part of editing an EffDir is inputting the Model Name Key in at the end of the file.  Scroll down and off to the side, in the area with all the dots (on the right), you'll start to see "preview_" something.  If you've read redlotus' Interchange Tutorial, you may remember him mentioning converting the Model Name Key into ASCII Hex Code and inputting it in with all the other numbers on the left side.

As it turns out, there's a far easier way.  It is possible to simply go over to where it says "preview_" and simply type in your desired Model Name Key--no ASCII Hex Code conversions required.  You will, however, need to keep it within the current length.  The "_red" part that is on the end of the second and fourth occurences also needs to remain in tact, as it references a special "red" effect that will turn the preview model red, as one would get when trying to place the piece somewhere one can't/shouldn't.

If you exceed the existing length, it will corrupt your EffDir file, immediately crashing the Reader.  Any attempts to re-open the EffDir upon getting back into the Reader will also result in the Reader crashing.

Code Select Expand

[IMG]http://img365.imageshack.us/img365/2717/effdir5de9.jpg[/img]
(NOTE:  There is actually a way to have more or fewer  characters in the Model Name Key.  Those red circled Hex numbers define the length of the Model Name Key, in Hexadecimal.  The second and fourth define the length of the "Red" Model Name Key--they will always be 4 characters longer.  However, there isn't really any need to do this, and it's very tricky, especially adding characters--doing it wrong will corrupt the EffDir and cause instant crashing.)

And now for the final part--the way in which RUL 0x10000000 references the EffDir.  As I mentioned earlier, the IID of the EffDir should generally correspond to the AutoTileBase defined in the RUL for the puzzle piece. 



The area circled in red is where the EffDir and RUL come together.  The "Piece" line must end with the IID of the Preview Model (the numbers before it cover X offset, Y offset, rotation and flipping of the Preview Model), and the PreviewEffect line must match the Model Name Key defined in the EffDir.

[JoeST]

sorry to be pedantic but:

Now for the fun part.  See the number circled in red?  That is a reference to the IID of the Preview Model.  In this case, the IID of the Preview Model is 0x5CA01405.  In EffDir files, the IID is expressed backwards in 2-bit hex chunks.  So, 5CA01405 becomes 05 14 A0 5C in the EffDir.

each hex digit represents 4 bits so each of those 2-digit hex chunks is a full byte.

Other than that it is a fantastic tutorial

Joe

Thanks for catching me there, Joe.  I've fixed it. :-) -Alex