Ptah - A Primer

by Brent Bartels

When Mithro first mentioned writing status reports, I considered the idea carefully and then simply forgot about it. A few days later, someone in IRC (I won't mention any names Demitar) 'pinned me to the channel', tactfully asked how to 'make Ptah do something useful', and said he would 'force' me to write an article for the CB. I guess that was a hint.

What can Ptah do for me?

The short answer is "Not Much". People are getting excited about formats right now, and are eager to move away from things like .iso, but Ptah as well as the libs that support it aren't quite ready.
Here's the long answer:

  • Ptah loads maps : - BLADE, iso and MIM in order of preference.
  • Ptah finds media : - You can specify what paths you want to be searched for external files. This system is changing should eventually use a symbol hierarchy to find media. I'm trying to implement the media part of aloril's semantic maps. The heart of this system is 4 files without any major dependencies. I'm hoping that it will be useful to others.
  • Ptah draws polygons : - Left clicking adds points and right clicking closes polygons. With the square tool only one left and one right click are required.
  • Ptah applies textures to polygons : - By right clicking you can get to a dialog that lets you change the 'Fill' type of the polygon that's currently selected. If your lucky Ptah may even let you create a new Fill type.
  • Ptah can undo : - All write operations to the CoalDatabase are handled by a command 'interpreter' and all operations are reversable (at least right now). Right now the addition and removal of polygons, and the application of textures can be undone.
  • Ptah handles multiple documents and views : - You can't open multiple copies of the same file but you can open multiple maps and bring up multiple views of the same map. Changes made in one view should be reflected in the others.
Here's some stuff that's on the not so distant horizon:

  • Addition of new fill types : - This is very close.
  • Placement and creation of objects
  • Take a popular .iso map and convert it to BLADE : - I'm hoping that doing some actual work with Ptah will reveal it's limitations.
  • Ability to search for media with cvs, ftp, or http
  • Switch to a new and improved COAL API
Here's some cruft that you may see lying around that doesn't work yet:

  • Views Menu : - Nothing in the Views menu works
  • Cut, Copy and Paste : - These operations used to work but were crippled when I made the command interpreter. Shouldn't be long...

What you can do for Ptah

  • Check it out of CVS. Read Install and Instructions and try it out. If it's not doing something I claim it should send me an email at bartelsb at If I can recreate the error I'll try to fix it.
  • If you have a patch please send it to me. I'm only going to be able to support MS Windows and Linux (probably only RedHat specifically) so help from people on other types of systems is welcome.
  • Getting dialogs just right in this kind of environment is tedious. It requires a lot of tweaking, compiling and clicking. If these are some of your favorite activities then your a prime candidate to become a Ptah developer.

A Walk Through

Start by opening a document ( File -> Open ) or creating a new one ( File -> New ). You'll see a globe icon appear in the left hand window. Ptah tries to emphasize the separation between the data and the way you view it, so it's not enough just to open the file. The default way to view worlds (the only way at the moment) is called a Blueprint View. This has a top-down viewpoint and grid lines. Double click on the globe to view the map or ,if the globe is selected, simply hit enter. Your tool bar buttons should light up.

Ptah will tell you if it was unable to open any media references found in the map. Any polygons that reference missing media will be set to a default fill type and color, which is plain white. Currently there are three modes in Ptah that can be selected either by clicking on the tool bar or by using the keyboard. The modes are as follows:

  • Selection ( the arrow or 's' key ) : - Selecting polygons will cause them to become highlighted. Select multiple polygons by holding down the control key. You can also drag polygons in this mode. Right clicking will raise a pop-up menu. The choices depend on the location of the mouse pointer in the document.
  • Drawing ( the point or 'd' key ) : - Left clicking adds points and right clicking closes polygons. While adding points the delete key will remove the last point and right clicking before there are three or more points will remove all points. Newly created polygons are selected.
  • Square ( the squares or 'b' key ) : - This is similar to the above but a left click specifies the top left corner of a rectangle and a right click makes the bottom right one.
Other tools are:
  • Zoom Level ( the magnifying glasses ) : - This controls the size of the squares in the grid. Polygons automatically resize when the grid size is changed.
  • Path Editor ( looks like a list box ) : - Opens up a dialog that you can use to edit the paths that Ptah uses when searching for media.
  • Landscape Editor ( right click when a polygon is selected and hit 'properties' ) : - Use this dialog to change the layer and fill type of the chosen polygon. Pressing the 'New Fill' button will let you select a .png file and a name that will create a new Fill and add it to the list of selections. Ptah won't actually show the texture on the polygon. No, I'm afraid that would be too cool. It selects a color that's representative of the texture (most of the time) and uses that instead.
  • Undo ( right click and select 'Undo name of operation' ) : - Ptah keeps up with all the changes made to databases and each one is tagged with a name like 'Apply texture' if you've made any changes you'll be able to see the latest one when you right click. When a change is undone it is removed from the 'command stack' and the change made before that will become available for undoing.
Assorted tid-bits :
  • Pressing delete removes any highlighted polygons from the map.
  • When you press the 'shift' key the display will pan in a direction determined by the position of the mouse.
  • Pressing the 'p' key changes the way the grid is displayed, either in the background, the foreground or not at all.

After you've made changes to a map you can save it under the same or a different name but be careful. If you don't get a message box that confirms that you saved, you probably didn't. Make sure the globe on the left is selected for the world you want to save and try again. You are free to close a view (at least in Windows) any time you like without losing changes. Just double click on the globe to reopen the map.

That's about all for right now. Keep checking CVS. Ptah is fairly awkward and incomplete right now but it gets a little bit of my attention everyday. Here's some screen shots just for kicks.

In Windows In Linux