Tangram Configuration and Files

Tangram (both game and editor) expect a certain directory structure and assume certain files existing.

Tangram directories and files

data A directory containing 3 files that configure the game and the editor.
puzzles Contains all the puzzle files and corresponding images.
textures Contains all the Tangram textures.
Tangram Editor.exe Executable for the Tangram Editor.
Tangram.exe Executable for the Tangram game.
iconv.dll Library used by the libxml2.
libxml2.dll Library used by the game to work with xml files.
SDL.dll Graphics library used by the game.
SDL_image.dll Image library use by the game.

Inside "data" directory

game_parameters.xml Controls several default puzzle and game parameters.
start.xml Contains the start positions of the game blocks.
system_parameters.xml Controls several system and interface parameters.

Inside "puzzles" directory

*.xml Puzzle files (for instance "hat.xml").
*.bmp Corresponding 256x256 puzzle images (for instance "hat.bmp")

Inside "textures" directory

background.bmp 128x128 texture of game board background.
easy-button.bmp 128x128 bitmap for easy difficulty menu button.
exit-button.bmp 128x128 bitmap for the quit game button in the menu.
game-board.bmp 128x128 texture for the actual game board (red tinted by the game).
hard-button.bmp 128x128 bitmap for hard difficulty menu button.
left-button.bmp 128x128 bitmap for the left (next puzzle) button in the menu.
medium-button.bmp 128x128 bitmap for medium difficulty menu button.
null-study-image.bmp 256x256 bitmap for puzzles without images (and for editor).
right-button.bmp 128x128 bitmap for the right (previous puzzle) button in the menu.
sidebar-exit.bmp 64x64 texture for the return to menu (or quit in editor) button in the sidebar.
sidebar-hint.bmp 64x64 texture for the hint button in the sidebar.
sidebar-reset-view.bmp 64x64 texture for the reset view button in the sidebar.
sidebar-reset.bmp 64x64 texture for the reset block position button in the sidebar.

File structures

All puzzle and configuration files are written in the XML structure. It is very easy to read and edit, with any text editor. XML files are built from elements. Each element can contain several attributes (or none) specific to it, as well as other elements, and text. Or none at all.

Here is how to define an element, with two attributes and a two sub elements:

<element-name attribute1="value" attribute2="another-value">
  <sub-element1>
    sub element1 content
  </sub-element1>
  ...some text that belongs to element name...
  <sub-element2>
    ...sub element2 content...
  </sub-element2>
</element-name>

An element that has no content can be define thusly:

<element-name attribute="value" ..(many attributes here)... />

The XML specification and many documents and tutorials can be found on World Wide Web consortium's website.

Structure of "game-parameters.xml"

<?xml version="1.0"?>
<game-parameters min-docking="..." max-docking="...">
  <verifier type="..." horizontal="..." vertical="..."
            transform="..." distance-threshold="..."
            solution-scale="..." blocks-scale="..."/>
</game-parameters>
game-parameters attributes
attribute-name type explanation
min-docking number A positive real number describing default minimum docking distance.
max-docking number A real number larger than max-docking describing default maximum docking distance
verifier attributes
attribute-name type explanation
type string Must be "rendering-verifier" for now. designed for possible future expansion.
horizontal integer Width of the rendering buffer.
vertical integer Height of the rendering buffer.
transform string
"not-transformed" blocks must be exactly inside solution
"translated" blocks must have the same orientation as solution, but it may be anywhere
"translated-and-rotated" the blocks may be anywhere and also rotated from the solution
distance-threshold number A number in the range 0..1.
solution-scale number A real number above 1.0 that determines scaling of the solution when testing.
blocks-scale number A number below 1.0 that determines scaling of the blocks when testing.

The verifier is the system component that determines when a game is solved. The rendering verifier works by rendering the solution to a buffer, and rendering the game blocks on the buffer. Thus testing if the game blocks are inside the solution or not. To overcome user inaccuracies, the solution is scaled up (by solution-scale) and the blocks is scaled down (by blocks-scale). Also, to overcome rotation of the solution, the rendering verifier finds the farther point from the blocks center, matches it to the same vector on the solution, and rotates it to match the same angle. It keeps doing that for closer and closer points, until it finds a valid solution match or until in finds a point which its distance from the center is distance-threshold multiplied by the farthest distance. The rendering verifier is currently the only type of verifier.

Structure of "system-parameters.xml"

<?xml version="1.0"?>
<system-parameters screen-width="640" screen-height="480" 
  game-size="1000.0" bpp="16">
  <interface-parameters view-rotate-speed="25.0" rotation-units="32" 
    doubleclick-ms="300"/>
</system-parameters>
system-parameters attributes
attribute-name type explanation
screen-width integer Width of screen.
screen-height integer Height of screen.
bpp integer Bits per pixel: 16 or 32. This attribute can be omitted to use the desktop's bit depth.
game-size number The width and height of the game board.
interface-parameters attributes
attribute-name type explanation
view-rotate-speed number The view rotation speed in degrees per pixel.
rotation-units integer Default units ("degrees") in a circle.
doubleclick-ms integer Number of milliseconds between two consecutive clicks for them to be a double click.

Structure of "start.xml"

The same as any other puzzle, with the difference that there is no "parameters" element.

Structure of a puzzle .xml file

<?xml version="1.0"?>
<tangram-game>
  <parameters max-docking="30.000000" min-docking="0.500000" 
  rotation-units="32"/>
  <entity-list>
    <entity>
      <transform rotate="0.000000" translatex="335.927429" 
        translatey="361.989237" scale="1.000000" flip="true"/>
      <polygon>
        <point x="-33.333333" y="-33.333333"/>
        <point x="-33.333333" y="66.666667"/>
        <point x="66.666667" y="-33.333333"/>
      </polygon>
    </entity>
    <entity>
      <transform rotate="270.000000" translatex="401.552429"   
        translatey="360.947571" scale="1.000000" flip="false"/>
      <polygon>
        <point x="33.333333" y="66.666667"/>
        <point x="33.333333" y="-33.333333"/>
        <point x="-66.666667" y="-33.333333"/>
      </polygon>
    </entity>
	...(other entities here)...
  </entity-list>
</tangram-game>
element meaning
tangram-game This element can have one "parameters" element inside it, and MUST have one "entity-list" inside it.
parameters The attributes of the "parameters" element override those in "game-parameters.xml" and "system-parameters.xml". This element is optional.
entity-list Defines a list of entities that make up the game solution. Can have as many "entity" sub nodes as you want. However, all the files in the "puzzles" directory must have the same number of elements as in "data\start.xml".
entity Defines a single polygon block, with transformations. Can have a "transform" sub-element. MUST have a single "polygon" sub-element.
transform These attributes define transformations applied to the current block, with its center as the origin. The attribute "rotate" is rotation angle in degrees, "translatex" and "translatey" define translation, "scale" defines scaling and flip is horizontal flipping (i.e x --> -x).
polygon Contains a list of 2D points defining a simple, convex, counter-clock-wise polygon. Should have at least 3 points.
point Defines a single 2D point with x and y.

Note that these files can be easily generated by hand, but it is better to use the editor for these.

The image for the puzzle is taken from the .bmp file in the "puzzles" directory with the same name as the .xml file. If no such file exists, "textures\null-study-image.bmp" will be used instead.

Texture and image files

Simple windows bitmap files, which can be generated by almost any graphics software, including mspaint.