Ck456Tli » TileInfo resource editor for Keens 4,5,6 version 3.2 » released on May 6, 2007 research by adurdin » program by The CK Guy

WHAT DOES THIS PROGRAM DO?

This program allows the Keener to alter tile properties. This is most useful when the Keener is also a Modder, and wishes to create a few new tiles to use, or perhaps to create a whole new set of tiles.

WHAT DOES THIS PROGRAM NOT DO?

This program does not alter the appearance of the tiles. (Use adurdin’s excellent ModKeen2 for that purpose.) It does not let you create new Keen levels. (Use TED5 or possibly Keen: Next for this.) And lastly, this program does not let you create completely new kinds of properties for tiles. (You’re on your own for this one.) This program only lets you change the tiles’ properties to those of existing tiles.

REVISION HISTORY (feel free to skip this if you want)

• Release One — Put together on November 18, 2003 — First public release. Written in QuickBasic, and thus a DOS program. Rather clunky interface, but gets the job done. It requires you to specify the filename on the command line (oh no!) and has very bad documentation and various other idiosyncrasies. In general, it just feels far from finished. (In other words—it’s garbage. Don’t use release one. Use this nice shiny version you just downloaded. Ooh.)

  Three eventful years pass … (during which ModKeen2 is released, making this program actually useful)

• Version 2.0 — Built on December 26, 2006 — This is a complete rewrite from release one. It is a Windows program, with a simple, but clean and hopefully intuitive, interface. This adds a few features—save as, patent-pending ;-P tile selection—but the main improvement is just the nicer interface. I also (horrors!) have removed a feature—extraction of the TileInfo resource from the Keen executable. This was a pain in the old DOS version, and would have probably been a pain in this Windows version. Instead, I have opted to just include the default TileInfo resources Keen?.tli, pre-extracted from the executables by yours truly.

• Version 2.1 — Built on December 30, 2006 — Fixed some readme.txt errors. Completely new “status” mechanism—I thought that old textbox was kind of cheesy. Some screens are rearranged a bit. (Big deal!) More importantly, entering bad tile numbers shouldn’t totally crash the program anymore. Now the file operation buttons are located outside the tabs, so they’re always accessible. The “File Operations” tab has been renamed “File Information” because it no longer does file operations. Allow specifying foreground tiles by the coordinates of their masked part in the bitmap. (ahem—not really, see version 2.2)

  Also — You may have noticed that the executable is now smaller and starts faster. This is because I am using a completely different build method: version 2.0 was built by translating the Euphoria 3.0.1 program into a tokenized version, and appending that to the interpreter. Version 2.1 was built by first translating the program into C, then compiling it with Open Watcom 1.5, then attaching the icon as a resource, then compressing it with UPX 2.01. The process takes much longer (several minutes instead of several seconds), but it does produce a smaller, faster executable.

• Version 2.2 — Built on January 1, 2007 — bugfix & docs release — Happy New Year! — Well NOW we allow specifying foreground tiles by the coordinates of their masked part in the bitmap. In version 2.1, we were taking the x-coord mod 18*256 instead of mod 18*16. (Just plain dumb.) Also—in version 2.1, I said I used Open Watcom 1.4; it was actually 1.5 (not a big deal, but I thought I’d mention it). And readme.txt is now readme.htm—and I’ve fixed miscellaneous typos and made various clarifications.

• Version 2.3 — Built on January 4, 2007 — Here it is—the feature everyone’s been waiting for! Yes, it’s tile selection by clicking a picture!!! Just click the big “.BMP” button on the “Background Tiles” or “Foreground Tiles” tab, as appropriate, select the proper ?TIL000?.BMP file, and go!! The select-by-coordinates method is now gone. I also updated a lingering readme.txt reference. (Hey—the shortest notes, the biggest news!)

• Version 2.4 — Built on January 6, 2007 — Increased how much clicking on the scrollbars change them by, making them more useful. There is no longer a horizontal scrollbar—it was just making the code uglier, and didn’t really help the usability of the program. I also changed around the internal workings of the scrollbar/tile display/blitting mechanism. <rant>Can you believe it?! I had to write the code for handling the scrolling myself! I had to calculate the source and destination coordinates for the blit operations! I needed to calculate the absolute coordinates clicked in the bitmap based on where in the window the click was together with where the scrollbars are!</rant> And “Nerual Stunner” had been there since version 2.0! Hadn’t anyone noticed?! And “[ Unknown #5 ]” is now “Moving platform arrow [K5+6]” (and “[ Unknown #6 ]” is now “[ Unknown #5 ]”). The “File Information” tab looks a little different now. The screen layout (i.e., where the tile-selection windows come up) has been changed—hopefully now more usable. The default locations of them are now so that all three windows (two tile-selection windows and main window) do not overlap. I also removed two obsolete tooltip references to the old tile selection by bitmap coordinates. I’m also now including a color-coded version of the program’s source code in the distribution archive as well.

• Version 2.5 — Built on January 9, 2007 — The actual editing of the tile properties is now nicer. Whenever you click in any of the edit boxes, its contents are automatically cleared, so you can immediately enter the new information. Also, pressing escape with one of the edit controls selected will reset that whole screen to the original values stored in memory. Changed the tooltips’ text a bit. There is now a mechanism to verify opening a new file or quitting the program when the loaded file has been changed but not saved. In adding this, I discovered and fixed a bug that’s been there since back in version 2.0. (The scenario—you click open, then load a file, then click open again, then click cancel, then click save, then click yes—the program used to crash. The trouble was that the filename was getting reset to “” when you clicked open but then canceled.) I commented the source a bit, and the HTML version no longer goes way off the side of the screen—it wraps now. And lastly, I fixed documentation to correctly say the commands for patching the Keen executable. They’d been somewhat wrong since version 2.0, and even more wrong since version 2.2.

  Also — Sometime after this release and before the next one, a separate subforum on Keen: Modding was created for my program! Woohoo! That’s how I know it’s important!

• Version 2.6 — Built on January 14, 2007 — Dropdown menus are now more organized and readable. More typos are fixed. (“keygen holder”…sigh.) There were a couple of “(?)” entries in the MiscFlags related to the switchable zappers in Keen 6—now after a few minutes of research, these flag values are relabeled. The “your file has been modified” mechanism is now a lot smarter. (That is, it used to think you changed a tile property when you clearly didn’t.) Also, the mouse wheel now lets you scroll through the tile picture. There should now be no blatantly unfinished aspects of the program. (These are famous last words, but we’ll see.)

• Version 2.7 — Built on January 15, 2007 — The shazam! release — Yet another little feature, though probably the most significant since version 2.3: a way to show you what tile was selected on the bitmap. The original TileInfo (for Keens 1,2,3) had this, and it was very useful. This feature even more important for Keens 4,5,6 than Keens 1,2,3, because it is often hard to tell where the tile boundaries are in the bitmap, mostly due to the tilted perspective and sloped floors. Fixed some lingering strange bugs with the tile-selection windows. (On the second and subsequent bitmaps loaded, the bottom part would be cut off, unless you resized the window, then it would behave correctly. It was a result of the conflict between the window size and the usable client area size.) The source code is also now more readable—when long lines of source wrap, all subsequent lines are indented. (Okay, hopefully this release will be able to just sit there and not be updated in like a day or two. This has been pretty intense. Eight releases in three weeks! I’d like work to slow down a bit on here and actually have people use it for mods. In other words, yes working on this is fun but I’d like to take a break and slow down.)

• Version 2.8 — Built on January 18, 2007 — Cleanup release. When you mouse-wheeled up at the top or down at the bottom of the tile-selection screens, the yellow lines would flicker. Gross. That’s fixed now. When focus switches to a particular tile-selection screen, the main program will automatically switch to the appropriate tab. You can also now hold down the left button, and drag the mouse around—even roll the wheel—and select many different tiles in succession. (This is not a particularly useful feature, but adds a more professional feel to the program.) Let’s see if this can be the last release for a while. At least I made it three days before this one.

• Version 3.0 — Released on February 13, 2007 — It’s been quite a while since last release (well, relatively speaking, anyway). Large rewrite. Rather different appearance. You’re now forced to load a file and two bitmaps right away, and you cannot reload them later (except by quitting the program). Everything is now in one window—no more separate windows for selecting tiles. When you select tiles, enlarged versions of them are shown. The dropdown menus are now positioned differently, and the Left/Right/FrontFlag checkboxes are now toggle buttons, which is all a bit more Keen 1,2,3 TileInfo-like. A new “Help” button that opens up readme.htm. The dropdown menus now only show values associated with the episode of the TileInfo file. No “unknown” values are initially included—these are now added as the user selects tiles with unknown flag values. And the check-if-the-file-has-been-modified mechanism still wasn’t working—saving the file did not mark it as unmodified, and changing the Left/Right/FrontFlag did not mark it as modified. (Clever.) Put some stuff into the docs about about the different versions of Keen.

• Version 3.1 — Released on April 12, 2007 — You can now control-click and drag to scroll the tile selection panels. (Yes, I know this is less than ideal, but now almost everyone has a mouse with a wheel.) To create animating tiles you now right-click in the tile selection panel to specify the target tile, instead of specifying an offset in a textbox. Animation timing is now specified by a scrollbar. You can now use F11 and F12 to copy and paste tile properties. Put a section in the docs on the flag values recognized by the program. Also, last release I accidentally lost the information about Euphoria and Win32Lib from the about box; they’re back now. (Also: I’m now using the new version of Euphoria, which is 3.0.2. And at some point I switched from UPX 2.01 to UPX 2.03, but I don’t remember exactly when. Oh, and I put in the new Keen: Modding address, woohoo!)

• Version 3.2 — Released on May 6, 2007 — Changed the clipboard operation quite a bit—there are now four of them. See the docs below for more information. Put in a little welcome dialog at the very beginning of the program so you aren’t immediately presented with a (potentially) confusing “Open” dialog box. Changed what happens when there is a problam loading a TileInfo resource or a bitmap of tiles—previously, the program would alert you that there was a problem, and then quit. Now it gives you the option to select a new file or to quit. Fixed a bug where the program didn’t correctly recognize when the mouse pointer was in one panel or the other. I wasn’t taking into account how far the whole window was from the upper-left hand corner of the screen—the farther it was, the bigger the error. (And since the window is by default centered, if you have a high resolution, stuff might not work at all.) And lastly, the color-coded source file is now much smaller (less than half the size of last release, even though the actual source is longer) because I’m using a cleverer method to generate the HTML.

A BIT OF BACKGROUND

First of all, these docs assume a good knowledge of CKPatch, Commander Keen built-in resources, and just modding in general. For a good introduction to these topics, check out the “Modding Tutorials” on Xtraverse’s “Beyond the Pogo” website at dosclassics.com/keen.

(Now that we’ve weeded out the riffraff, we may proceed unencumbered!)

The properties of each tile are encoded in various “flags”. Background tiles have two flags and foreground tiles have seven. The term flags here is rather misleading, because this seems to imply that each one is either on or off. This is far from true—each flag for each tile is represented as a byte in the resource, so in theory a flag could have one of 256 values, but this does not happen in practice.

The flags for background tiles, listed in the order they appear in the TileInfo resource:

• TimeFlag
• AnimFlag

The flags for foreground tiles, listed in the order they appear in the TileInfo resource:

• TopFlag
• RightFlag
• BottomFlag
• LeftFlag
• AnimFlag
• MiscFlag (including the pseudo-flag ForegroundFlag)
• TimeFlag

Altering the properties of a tile consists of changing the values of one or more flags for that tile. Now we’ll go into specifics on the various flags.

• AnimFlag — (For foreground and background tiles) For tiles that do not animate, this is zero. For animating tiles, it is a relative offset to the next tile in the animation sequence. This is stored as a signed byte, so the offset can be from -128 to +127.

• TimeFlag — (For foreground and background tiles) For tiles that do not animate, this is zero. For animating tiles, it is the amount of time spent on this tile in the sequence. The time unit is not known. To quote from an old document of adurdin’s: “The time is specified in UNITS, from x00 to xFF. A value of x95 is approximately equal to 2 seconds. Values lower than x02 may animate only sporadically.”

  Also — These flags are not just used for tiles that animate “by themselves”. Most of the time when tiles turn into other tiles (on switch to off switch and back, empty keygem holder to keygem holder with key, bridge opening/closing, keygem door opening, Keen 5 keycard door opening, etc.), the situation is handled by animating tiles. The AnimFlag for one tile points to the other, but the TimeFlag is set to zero.

• TopFlag — This specifies what the top of the tile is like. It can be a flat solid top, an open top you can fall through, a particular slant, solid but has a pole going through, etc.

• LeftFlag and RightFlag — These are zero if you can enter from that side, and one if the tile is solid on that side.

• BottomFlag — This specifies what the bottom of the tile is like. If you specify the TopFlag to be solid, but specify the BottomFlag to be “jump through”, you will get a tile that you can jump up through and land on, and to get back down through, you look down and jump. Some examples of this kind of tile are the “narrow” floors in Keen 4, the holes in Keen 5, and the tree limbs in Keen 6.

• MiscFlag — This is the most complicated flag. It encodes many of the special properties that tiles can have (such as being deadly, being an item with a certain point value, etc.). All of these are actually encoded in the lower seven bits of the flag. The high bit specifies whether or not the tile is to appear in front of Keen and other sprites, as opposed to behind them as most foreground tiles do. In this program, this is implemented as a separate pseudo-flag, ForegroundFlag.

HOW TO USE THIS PROGRAM

Before you even fun the program, you will need three things: a TileInfo resource dump, a standard bitmap of the background tiles (18 tiles per row), and a standard bitmap of the foreground tiles (also 18 tiles per row). For the TileInfo resource dump, you will probably be starting with one of the Keen?.tli included in Ck456Tli(v3.2).zip. For the two bitmaps, probably the easiest way to get these is to use ?TIL0000.BMP and ?TIL0001.BMP exported with ModKeen2.

Now you can start up the program. Click “OK” at the introductory welcome dialog. In the next dialog box that pops up, select the TileInfo resource file you want to edit, then click on “Open”. In the next window, open the background tile bitmap, and in the window after that, open the foreground tile bitmap. (For the last two windows, the default filename mask corresponds with the filenames used by ModKeen2.)

Now, the main program will start. The narrow section on the left has four buttons on top (“Save”, “Save As”, “About”, and “Help”, which have the obvious purposes), and below them various information about the loaded file. Now, especially if you’re working from one of the default TileInfo files that come with this program, I would recommend that you immediately click “Save As” and save to a new file.

To edit the properties of a tile, click on it in the pictures of the tiles. An enlarged version will appear in the top portion of the program. (For foreground tiles, an enlarged version of the mask will also appear.) Use the mouse wheel to scroll the tile pictures up and down. You can also control-click and drag with the left mouse button to scroll if your mouse doesn’t have a wheel.

For background tiles, you can edit the animation properties. To specify what tile this tile animates to, right-click it in the tile selection panel. If a tile animates, the target tile is outlined in a double red border. Note that tiles can only animate up to 128 tiles before them and up to 127 after them. By moving the scrollbar, you can change the amount of time spent on the tile while animating (0 to 255 time units).

For foreground tiles, you can also edit the animation properties (and they work the same way), but you can also edit several other properties. Above the enlarged pictures of the tile and its mask is a dropdown menu where you can select the properties of the top of the tile. Similarily, the dropdown menu below lets you select the properties of the bottom of the tile. Pushing in the buttons to either side signify that Keen (and other sprites) cannot enter the tile from that side. (Note that these are almost always set or cleared together. One-way tiles do not work as well in Keens 4,5,6 as they do in Keens 1,2,3.) Off to the right is another dropdown menu, which lets you change special properties of the tile. Lastly, when the “FRONT” button is pushed in, it means that the tile appears in front of Keen and other sprites rather than behind them.

And now, some keyboard shortcuts: For both background and foreground tiles, pressing escape resets the properties to their previous values. Pressing F1-F4 copies the current tile’s properties to internal clipboard 1-4, respectively. Pressing F5-F8 pastes the properties on clipboard 1-4 to the current tile. Pressing F9-F12 pops up a dialoge box displaying the contents of clipboard 1-4. You can even hold one of F5-F8 down as you drag the mouse around, applying the properties to many tiles quickly.

There is something important to note about the target tile for animation: this is stored as a relative offset to the target tile. This means that when you copy the properties from tile A and paste them to tile B, the target animation tile of tile B isn’t the same as that for tile A, but it is the same relative tile, which is usually what you’d want, anyway. Also note that there are not different kinds of clipboards for the background and foreground tiles—when you copy/paste a background tile, only the animation and timing properties are affected/used, the other properties of the clipboard are unchanged/ignored.

(You may be wondering how the program decides whether the ESC, F1-F8 keypresses apply to the background or foreground tiles. It’s actually quite simple: if your mouse is in the background group in the window, the command applies to the background tiles. If it’s in the foreground group, it applies to the foreground tiles. If the mouse isn’t in either group, nothing happens.)

To save the file click either “Save” to save to the current file, or “Save As” to save to another file. To use the TileInfo resource in you own Keen game, you can patch it into memory by putting one of these lines into your CKPatch script file:

%patchfile $249C2 <filename.tli> # for Keen 4
%patchfile $25B22 <filename.tli> # for Keen 5
%patchfile $25212 <filename.tli> # for Keen 6

Note that these are for Keens 4,5,6 version 1.4, not version 1.4 GT (distributed by Goodtimes Software), nor version 1.0 (nor any of the other myriad interim Keen 4 versions). This is the standard version for all modding in episodes 4,5,6, just as version 1.31 is the standard for Keens 1,2,3. If you must know, the offsets for Keens 4,5,6, version 1.0, are $23742, $24B12, and $23DE2, respectively. Modding from versions other than 1.4 is not recommended.

FLAG VALUES (feel free to skip this if you want)

Here are the various flag values recognized by the program:

ABOUT THE SOURCE CODE

The program’s source code is now included in the distribution. This is provided for curious users, and will probably not be of interest to most people. The source is color-coded in the HTML file source.htm. I’m not releasing this out into the public domain—you need to ask me for permission before you distribute anything derived from it. (I’m allowed to say no!)

The program is written in Euphoria (version 3.0.2, to be precise), an obscure but amazing language I’ve grown to love over the years. [begin plug — The greatest thing about Euphoria is the flexible but simple data structures. The types of data are: atoms (these are numbers), and sequences (these are finite ordered collections of atoms and sequences). Sequences can contain any combination of other data, and are completely dynamic at runtime. With the one data structure of a sequence, you can implement arrays, multidimensional arrays, structures, trees, stacks, linked lists, and pretty much anything else you can think of. What about strings? These are just sequences of atoms, which are the ASCII codes. The string "ABC" is exactly the same as the sequence {65, 66, 67}. Anyway, this language is completely awesome and fully recommended. On October 17, 2006, it went completely open source (no more paying for advanced features!), so go get your copy today. — end plug] It uses Win32Lib (version 0.60.6), which is pretty much a gigantic set of wrapper routines for the Windows API. (To be honest, the library could be a lot nicer and more internally consistent.)

CLOSING REMARKS

Special thanks to adurdin for doing the initial research on the TileInfo resource format a while back. He’s been the hub of the Commander Keen modding community for several years. Thanks to Xky Rauh for prodding me into completing version 2.0 of this program. Thanks to people who made suggestions on how to improve Ck456Tli over the past weeks. Thanks to various people for pressuring me into implementing a nice tile-selection interface. (Once I started trying to figure out how to do it, it wasn’t really that bad.) Ditto for the current-tile crosshairs. (And ditto for this part too.) And thanks to the entire K:M community for being awesome in general. (Notice that I’m pointedly not thanking the PCKF community. ;-P )

If you have any questions or comments, please post them on the “Ck456Tli” forum at Keen: Modding (www.keenmodding.org) or email them to me (theckguy@gmail.com). If you notice any bugs or inconveniencies (in·con·ve·nien·cy n, pl in·con·ve·nien·cies (21c): something that is inconvenient—from Webster’s 314^th Well-it’s-a-Word-Now-and-I-Don’t-Care Dictionary) or discover flag values that do not work as expected, please tell me! I always want to hear suggestions about how to improve this program.

I need you guys to go bug-hunting and let me know what you find. And while you’re at it, make sure you add to the KeenWiki. (Do you know that that was where I first found out that people thought my program wasn’t easy to use? You’ve got to let me know this stuff in the forums!)

I hope this tool is useful! Now let’s have some more mods!

The CK Guy
May 6, 2007