Haptek Authoring & Development Guide


HapTar files and the Targh tool

Haptek Inc
931 Pacific Avenue
Santa Cruz, CA 95060
November 2002

Overview and History

    HapTargh  is a tool for creating and modifying Haptek tar files (*.HTR).  HTR files were created as a simple means of grouping many files into a single 'archive'.  Just like most other Haptek files, HTR's can optionally be compressed. Every HTR has an optional bit of 'startup text' associated with it.   When the HTR is loaded into the Haptek Engine, this text will be processed by the Haptek Character Engine.  You can think of an HTR as a zip file for windows that has a bit of Haptek Hypertext associated with it, and you can think of HapTargh as something very similar to WinZip (perhaps a backwards half-breed cousin).

HTR's are used in PeoplePutty for all the accessories , and for wrapping up your final character for export to a web page.


What's in an HTR?

    Let's take a look at the arrow accessory that comes with PeoplePutty.  When you first run HapTargh it will look like Figure 1. A blank slate ready for your command.  You see in the top left corner, our mascot: a sea weary pirate with his jabbering parrot.....Arghhhh!   Below him (or her?) you see the File, View, Preferences, and Help menus.  Below that, a toolbar with common shortcuts is perched. Below the toolbar we have the Startup String and an edit box where we can enter text (more on that later).  Finally, below the Startup String, we have the main area where all the files will be listed if only we had opened an HTR file.  You can see there is a space for the File Name, the File Size, and the Date it was Added to the HTR.

Figure 1 -   just opened HapTargh

To open the arrow accessory,  I click File. Then, I click Open. I browse to the arrow.htr (found in a deep dark sub directory of PeoplePutty's environment directory).  Select arrow.htr and click Open.  Now HapTargh should look like Figure 2.  You can now see the name of the opened HTR in the title bar( right next to the pirate and his parrot).  Down below you see that the Startup String is filled with a Haptek Hypertext command to load arrowStartup.hap.   And below that you see the list of files contained in arrow.htr, with their sizes and dates added.

Note:  HTR files have gone through many transformations, as has HapTargh itself, thus many older .htr files will not have dates specified in them, if no date is specified inside an HTR, then the current date will be listed under Date Added, as it was in Figure 2.  IN FACT, dates are completely meaningless here and should be ignored.

Figure 2 - opened arrow.htr

Startup String

Again, the Startup String lets you execute a Haptek Hypertext command when an HTR is loaded into the Haptek Character Engine.  This exists so that you can load an HTR with the "\load" hypertext command, and it will automatically set itself up properly in the Haptek engine.  For instance in Figure 2 we have the arrow accessory.  In order to load an arrow accessory, we must Load the arrow figure, position it in the right place relative to the figure in the scene, and use a Haptek Hypertext command to attach it to the figure.  This all happens in the arrowStartup.hap file which is included in the HTR itself, and is loaded by the Haptek Hypertext command in the Startup String.  This makes the arrow.htr a self contained unit that can be loaded into the Haptek API without explicit knowledge of its contents.   This is always how we use HTR's here at Haptek.

Adding, Removing, and Extracting

    You can add files to or remove files from the HTR file by dragging and dropping files from Windows Explorer, right clicking on the HapTargh program and choosing  the Add Files, or Remove files menu,   or by using the File menu.  You can Extract files from the archive the same ways.

Note:    if you Remove a file, it will be gone! Extracting a file will let you save a local copy of the file.
Note:    none of your changes will take effect on the HTR file you are working with until you SAVE it.

Compressing HTR Files

    By default, HapTargh compresses all HTR files when it saves them.   If you look under the preferences menu, you will see the "Auto-compress archive" menu item. If it's checked they will be compressed, if it's not checked HTR's will not be compressed when saved out.  HapTargh uses the same compression format as HapCompressor.


    HTR's can help you to organize your Haptek web site. It's much easier to download and load a single HTR file than it is to download 5 scripts, 3 texture maps, 5 background images, 24 character files, etc.   Just think, a single call to download and load your HTR which contains all of the other files.  This does wonder for your html and javascript code, eliminating scores of text lines.  Also since HTR's are compressed by default it can shrink the amount of data someone needs to download when they visit your site.. This is always a good thing!.  So Use HTR's.  Use HTR's! USE HTR's!!! YAY!!!!

Notes on filenames

Files which have been downloaded, decompressed, or de-tarred are recognized by the Player/API only by their filenames, regardless of the path preceeding them. That is, the API won't distinguish between "http://www.haptek.com/foo/hello.jpg" and "http://www.haptek.com/bar/hello.jpg", nor between two files named "hello.jpg" nested inside two different .haptar files. This is a shortcoming of the API, and may be corrected in the future.
For this reason, it is highly recommended to avoid common names like "hello.jpg" and use more specific ones like "john_hello_1.jpg".


The Haptek API uses a temporary folder to extract the files inside a HapTar file. This folder is the same as the one used by compression.

What More?

    That's about it, I think you will find the rest of HapTargh familiar ground if you are used to working with windows programs. Just to be explicit here, HTR files are meant for Haptek API use, and I wouldn't use them as a general purpose archive format.  For that use one of the more standard ZIP files.

    Ahh, Temporary Files, how could I forget.  When you first run HapTargh it will ask you for a directory to put it's temporary files in.  Any old directory is good.  By default, this will be in your haptek player directory.  If you need to change this directory you can do so using the Preferences menu.

A Song to sing while using HapTarghhhhhhh!

Cape Cod Girls
Traditional - As sung by Captain Jesse Schaffer

Cape Cod girls ain't got no combs,
Heave away, haul away!
They comb their hair with a codfish bone,
And we're bound away for Australia!

So heave her up, me bully bully boys,
Heave away, haul away!
Heave her up, why don't you make some noise?
And we're bound away for Australia!

Cape Cod boys ain't got no sleds,
They ride down hills on a codfish head.

Cape Cod mothers don't bake no pies,
They feed their children codfish eyes.

Cape Cod doctors ain't got no pills,
They give their patients codfish gills.

Cape Cod cats ain't got no tails,
They got blown off in northeast gales.

Cape Cod dogs ain't got no bite,
They lost it barking at the Cape Cod light.

Cape Cod girls they are so fine,
They know how to bait a codfish line.