This is an old revision of the document!
Table of Contents
Lazarus Hex Map Editor
1. Design Concept
The goal is to create a hex map editor using Lazarus and Free Pascal.
The editor will maintain two representations of the map:
- Working copy: A symbolic, abstract representation optimized for editing, data manipulation, and ease of rendering.
- Exported copy: An artistic representation intended for presentation, printing, or use in a virtual tabletop.
The working copy does not need to resemble the final map particularly closely. Significant liberties can be taken with its visual representation, provided that the underlying hex relationships remain correct.
The exported map will be generated from the working data rather than edited directly.
2. Working Grid Concept
The initial proposal is to represent the working map using rectangular cells rather than actual hexagons.
The cells are arranged in staggered vertical columns:
- Columns are vertically offset relative to their neighbours.
- Y coordinates remain constant within each individual column.
- The underlying storage can be a simple two-dimensional array.
- Neighbour relationships follow hexagonal topology rather than square-grid topology.
This approach offers several advantages:
- Simpler storage and indexing.
- Straightforward rectangular drawing operations.
- Easier mouse hit-testing.
- Simpler scrolling and zooming.
- Convenient rectangular selection and editing operations.
The logical representation remains a hex grid, even though the editor displays rectangular cells.
3. Hexagonal Orientation
The intended hexagon orientation is flat-top.
This means:
- The top and bottom edges are perfectly horizontal.
- The hexagons have their vertices pointing left and right.
- Columns are staggered vertically.
- The vertical offset alternates between adjacent columns.
This corresponds to the conventional flat-top, staggered-column hexagonal layout.
4. Working Cell Geometry
The working rectangles should be proportioned according to the geometry of the underlying regular hexagons.
The requirements are:
- The rectangle covers the full vertical extent of the hexagon, including its top and bottom edges.
- The left and right boundaries of the rectangle pass through the midpoints of the four diagonal hexagon edges.
Let:
- R = Hexagon radius (centre to any vertex).
- W = Hexagon width.
- H = Hexagon height.
For a regular flat-top hexagon:
Hexagon width = 2R Hexagon height = sqrt(3) * R
The upper-right diagonal edge, for example, runs between:
(R/2, H/2) (R, 0)
Its midpoint is:
X = 3R/4 Y = H/4
Consequently, the vertical boundaries of the working rectangle should be positioned at X = ±3R/4 relative to the hexagon centre.
This gives the following working rectangle dimensions:
Rectangle width = 3R/2 Rectangle height = sqrt(3) * R
The resulting aspect ratio is:
Width / Height = sqrt(3) / 2
≈ 0.8660254
The working rectangles are therefore slightly narrower than they are tall.
5. Column Staggering
Adjacent columns are vertically offset by half the height of the working rectangle.
ColumnOffsetY = RectangleHeight / 2
= sqrt(3) * R / 2
In other words, if the rectangle height is H:
ColumnOffsetY = H / 2
Alternating columns receive this offset.
6. Convenient Implementation Formulas
For implementation purposes, it is convenient to choose the desired working rectangle height first.
Let H be the working rectangle height.
The remaining dimensions are:
Hexagon radius = H / sqrt(3) Rectangle width = H * sqrt(3) / 2 Rectangle height = H Column vertical offset = H / 2
These formulas provide the geometric relationship between the symbolic working grid and the regular flat-top hexagons used in the exported map.
7. Implementation Considerations
The working map should be treated as a data structure first and a graphical representation second.
Potential implementation components include:
- A hex-cell data record.
- A two-dimensional array of cells.
- A neighbour lookup routine that accounts for column parity.
- Rectangular cell drawing using Lazarus TCanvas.
- Mouse-coordinate-to-cell conversion.
- A separate export renderer that converts working coordinates into actual hexagonal geometry.
An important design principle is to prevent the rectangular appearance of the working grid from influencing game logic.
Distance calculations, adjacency, area effects, and pathfinding must all use hexagonal relationships.
8. Development Direction
The next logical development steps are:
- Define the exact odd/even column neighbour relationships.
- Establish pixel-to-grid coordinate conversion for mouse interaction.
- Define the internal hex-cell record and map storage.
- Establish the conversion from working-grid coordinates to exported hexagon centres.
- Develop the artistic export renderer independently of the editor interface.
The central architectural decision is to keep the symbolic editing representation independent of the artistic presentation representation.
