n_iso_engine.h File Reference

Isometric/axonometric tile engine with height maps, terrain transitions, and A* pathfinding integration. More...

#include "n_common.h"
#include "n_log.h"
#include <allegro5/allegro.h>
#include <allegro5/allegro_primitives.h>
#include <allegro5/allegro_font.h>

Include dependency graph for n_iso_engine.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	CELL
	Cell of a MAP. More...
struct	ISO_DRAW_ENTRY
	Draw order entry for segment-sorted rendering. More...
struct	ISO_MAP
	Height-aware isometric map with terrain and height layers. More...
struct	ISO_PROJECTION
	Axonometric projection parameters. More...
struct	ISO_TILE_SEGMENT
	Single vertical segment of a tile: solid matter from bottom to top. More...
struct	ISO_TILE_SEGMENTS
	Per-tile height segments. More...
struct	ISO_VISIBLE_EDGES
	Per-tile edge visibility flags for height border rendering. More...
struct	MAP
	MAP with objects, tiles, skins (legacy structure) More...
struct	N_ISO_CAMERA
	2D isometric camera for viewport management. More...
struct	N_ISO_OBJECT
	Drawable object for depth-sorted isometric rendering. More...

Macros
#define	BLCK   3
	FLAG of a stopping tile.
#define	ISO_CORNER_NE   (1 << 1)
	Corner bitmask: northeast diagonal has higher terrain.
#define	ISO_CORNER_NW   (1 << 0)
	Corner bitmask: northwest diagonal has higher terrain.
#define	ISO_CORNER_SE   (1 << 2)
	Corner bitmask: southeast diagonal has higher terrain.
#define	ISO_CORNER_SW   (1 << 3)
	Corner bitmask: southwest diagonal has higher terrain.
#define	ISO_EDGE_E   (1 << 2)
	Edge bitmask: east neighbor has higher terrain.
#define	ISO_EDGE_N   (1 << 1)
	Edge bitmask: north neighbor has higher terrain.
#define	ISO_EDGE_S   (1 << 3)
	Edge bitmask: south neighbor has higher terrain.
#define	ISO_EDGE_W   (1 << 0)
	Edge bitmask: west neighbor has higher terrain.
#define	ISO_MAX_SEGMENTS_PER_TILE   2
	Max height segments per tile (ground + one elevated structure).
#define	ISO_NUM_CORNER_MASKS   16
	Number of possible corner mask combinations (2^4 = 16)
#define	ISO_NUM_EDGE_MASKS   16
	Number of possible edge mask combinations (2^4 = 16)
#define	ISO_NUM_MASKS   (ISO_NUM_EDGE_MASKS + ISO_NUM_CORNER_MASKS)
	Total number of transition masks (edge + corner)
#define	ISO_NUM_PROJECTIONS   4
	Number of built-in projection presets.
#define	ISO_PROJ_CLASSIC   0
	Projection ID: classic 2:1 isometric (~26.565 degree angle)
#define	ISO_PROJ_ISOMETRIC   1
	Projection ID: true isometric (30 degree angle)
#define	ISO_PROJ_MILITARY   2
	Projection ID: military/planometric (45 degree angle)
#define	ISO_PROJ_STAGGERED   3
	Projection ID: flatter dimetric (~18.43 degree angle)
#define	ISO_PROJ_STEEP   ISO_PROJ_ISOMETRIC
	Legacy alias: ISO_PROJ_STEEP maps to ISO_PROJ_ISOMETRIC.
#define	ISO_PROJ_WIDE   ISO_PROJ_STAGGERED
	Legacy alias: ISO_PROJ_WIDE maps to ISO_PROJ_STAGGERED.
#define	N_ABILITY   3
	FLAG of ability type.
#define	N_MUSIC   4
	FLAG of music type.
#define	N_OBJECT   5
	FLAG of object type.
#define	N_TILE   2
	FLAG of tile type.
#define	SWIM   2
	FLAG of a swimmable tile.
#define	WALK   1
	FLAG of a walkable tile.

Typedefs
typedef void(*	N_ISO_OBJECT_DRAW_FN) (float screen_x, float screen_y, float zoom, float alpha, void *user_data)
	Object draw callback.

Functions
int	camera_to_map (MAP **map, int tx, int ty, int x, int y)
	Center Map on given map coordinate, with x & y offset.
int	camera_to_scr (MAP **map, int x, int y)
	Center Map on given screen coordinate.
int	create_empty_map (MAP **map, const char *name, int XSIZE, int YSIZE, int TILEW, int TILEH, int nbmaxobjects, int nbmaxgroup, int nbmaxanims, int nbtiles, int nbanims)
	Create an empty map.
int	draw_map (MAP *map, ALLEGRO_BITMAP *bmp, int destx, int desty, int mode)
	Draw the map using its coordinate on the specified bitmap.
int	free_map (MAP **map)
	Free the map.
int	get_value (MAP *map, int type, int x, int y)
	Get the tilenumber of a cell.
void	iso_corner_to_screen (const ISO_MAP *map, int cx, int cy, float fh, float cam_x, float cam_y, float zoom, float *sx, float *sy)
	Project a tile corner to screen coordinates (canonical formula).
float	iso_diamond_dist (int px, int py, int tile_w, int tile_h)
	distance from pixel to diamond edge (0 at edge, 1 at center)
void	iso_generate_transition_masks (ALLEGRO_BITMAP **masks, int tile_w, int tile_h)
	Generate the 32 procedural transition alpha masks (16 edge + 16 corner).
void	iso_generate_transition_tiles (ALLEGRO_BITMAP ***tiles, ALLEGRO_BITMAP **masks, ALLEGRO_BITMAP **tile_bitmaps, int num_terrains, int tile_w, int tile_h)
	Pre-composite transition tiles (terrain texture * alpha mask).
int	iso_is_in_diamond (int px, int py, int tile_w, int tile_h)
	test if pixel (px,py) is inside the isometric diamond of size tile_w x tile_h
int	iso_map_build_draw_order (const ISO_MAP *map, ISO_DRAW_ENTRY *out, int max_entries)
	Build the draw order for segment-sorted rendering.
void	iso_map_calc_transitions (const ISO_MAP *map, int mx, int my, int *edge_bits, int *corner_bits)
	compute terrain transition bitmasks for a cell (Article 934)
void	iso_map_calc_transitions_full (const ISO_MAP *map, int mx, int my, int *edge_bits, int *corner_bits)
	compute per-terrain transition bitmasks with height filtering (Article 934).
void	iso_map_corner_heights (const ISO_MAP *map, int mx, int my, float *h_n, float *h_e, float *h_s, float *h_w)
	compute average corner heights for smooth rendering (Article 2026)
void	iso_map_draw (const ISO_MAP *map, ALLEGRO_BITMAP **tile_bitmaps, ALLEGRO_BITMAP ***transition_tiles, int num_masks, ALLEGRO_BITMAP **overlay_bitmaps, int num_overlay_tiles, float cam_px, float cam_py, float zoom, int screen_w, int screen_h, int player_mode, N_ISO_OBJECT *objects, int num_objects)
	Draw the full ISO_MAP with height, transitions, overlays, cliff walls, hover, and grid.
void	iso_map_free (ISO_MAP **map)
	free an ISO_MAP and set the pointer to NULL
int	iso_map_get_ability (const ISO_MAP *map, int mx, int my)
	get ability for a cell (bounds-checked)
int	iso_map_get_height (const ISO_MAP *map, int mx, int my)
	get height for a cell (bounds-checked, clamped)
const ISO_TILE_SEGMENTS *	iso_map_get_segments (const ISO_MAP *map, int mx, int my)
	get per-tile segments.
int	iso_map_get_terrain (const ISO_MAP *map, int mx, int my)
	get terrain type for a cell (bounds-checked)
ISO_VISIBLE_EDGES	iso_map_get_visible_edges (const ISO_MAP *map, int mx, int my)
	Compute which diamond edges of tile (mx, my) need a height border.
ISO_VISIBLE_EDGES	iso_map_get_visible_edges_segment (const ISO_MAP *map, int mx, int my, int seg_idx)
	Compute per-segment edge visibility for height border rendering.
float	iso_map_interpolate_height (const ISO_MAP *map, float fx, float fy)
	bilinear height interpolation at fractional map coordinates
void	iso_map_lerp_projection (ISO_MAP *map, float dt)
	smoothly interpolate current projection angle toward target (call every frame)
ISO_MAP *	iso_map_load (const char *filename)
	load ISO_MAP from binary file
ISO_MAP *	iso_map_new (int width, int height, int num_terrains, int max_height)
	create a new height-aware ISO_MAP with given dimensions
void	iso_map_randomize (ISO_MAP *map)
	randomize terrain and height for testing/demo purposes
int	iso_map_save (const ISO_MAP *map, const char *filename)
	save ISO_MAP to binary file (chunk-based format)
void	iso_map_set_ability (ISO_MAP *map, int mx, int my, int ab)
	set ability for a cell (bounds-checked)
void	iso_map_set_height (ISO_MAP *map, int mx, int my, int h)
	set height for a cell (bounds-checked, clamped)
void	iso_map_set_projection (ISO_MAP *map, int preset, float tile_width)
	set projection preset and snap to it immediately
void	iso_map_set_projection_custom (ISO_MAP *map, float half_w, float half_h, float tile_lift)
	set custom projection parameters directly
void	iso_map_set_projection_target (ISO_MAP *map, int preset)
	set target projection preset for smooth interpolation via iso_map_lerp_projection
int	iso_map_set_segments (ISO_MAP *map, int mx, int my, const ISO_TILE_SEGMENT *segs, int count)
	set per-tile segments on an ISO_MAP.
void	iso_map_set_terrain (ISO_MAP *map, int mx, int my, int terrain)
	set terrain type for a cell (bounds-checked)
int	iso_map_should_transition (const ISO_MAP *map, int mx1, int my1, int mx2, int my2)
	check if terrain blending should occur between two adjacent cells
int	iso_map_should_transition_smooth (const ISO_MAP *map, int mx1, int my1, int mx2, int my2)
	check if terrain transition should render between two cells (height-aware)
void	iso_map_smooth_corner_heights (const ISO_MAP *map, int mx, int my, float *h_n, float *h_e, float *h_s, float *h_w)
	compute smooth corner heights with slope clamping (for rendering)
void	iso_map_to_screen (const ISO_MAP *map, int mx, int my, int h, float *screen_x, float *screen_y)
	convert map tile coordinates to screen pixel coordinates
void	iso_map_to_screen_f (const ISO_MAP *map, float fmx, float fmy, float h, float *screen_x, float *screen_y)
	convert map tile coordinates to screen pixel coordinates (float version)
void	iso_mask_tile_to_diamond (ALLEGRO_BITMAP *bmp, int tile_w, int tile_h)
	Mask a tile bitmap to the isometric diamond shape.
const char *	iso_projection_name (int preset)
	get the display name for a projection preset
void	iso_screen_to_map (const ISO_MAP *map, float screen_x, float screen_y, int *mx, int *my)
	convert screen pixel coordinates to map tile coordinates (flat, no height)
void	iso_screen_to_map_height (const ISO_MAP *map, float screen_x, float screen_y, int tile_w, int tile_h, int *mx, int *my)
	height-aware screen-to-map conversion with diamond hit testing.
void	iso_screen_to_map_height_f (const ISO_MAP *map, float screen_x, float screen_y, int tile_w, int tile_h, int *mx, int *my, float *out_fx, float *out_fy)
	height-aware screen-to-map conversion returning fractional tile coordinates.
int	load_map (MAP **map, char *filename)
	Load the map.
void	n_iso_camera_center_on (N_ISO_CAMERA *cam, float world_x, float world_y, int screen_w, int screen_h)
	Center the camera so that a world point is at screen center.
void	n_iso_camera_follow (N_ISO_CAMERA *cam, float target_x, float target_y, int screen_w, int screen_h, float smoothing, float dt)
	Smoothly follow a world-space target (camera lerp).
void	n_iso_camera_free (N_ISO_CAMERA **cam)
	Free a camera and set the pointer to NULL.
N_ISO_CAMERA *	n_iso_camera_new (float zoom_min, float zoom_max)
	Create a new camera with the given zoom limits.
void	n_iso_camera_screen_to_world (const N_ISO_CAMERA *cam, float sx, float sy, float *wx, float *wy)
	Convert screen pixel coordinates to world coordinates.
void	n_iso_camera_scroll (N_ISO_CAMERA *cam, float dx, float dy)
	Scroll the camera by (dx, dy) world units.
void	n_iso_camera_world_to_screen (const N_ISO_CAMERA *cam, float wx, float wy, float *sx, float *sy)
	Convert world coordinates to screen pixel coordinates.
void	n_iso_camera_zoom (N_ISO_CAMERA *cam, float dz, float mouse_x, float mouse_y)
	Zoom the camera toward a screen-space point (e.g.
int	save_map (MAP *map, char *filename)
	Save the map.
int	ScreenToMap (int mx, int my, int *Tilex, int *Tiley, ALLEGRO_BITMAP *mousemap)
	Convert screen coordinate to map coordinate.
int	set_value (MAP *map, int type, int x, int y, int value)
	Set the tilenumber of a cell.

Detailed Description

Isometric/axonometric tile engine with height maps, terrain transitions, and A* pathfinding integration.

Provides data structures and utility functions for diamond-layout isometric maps with:

• Per-cell terrain type, height, ability, object, and music layers
• Configurable axonometric projections (classic, steep, wide, military)
• Map-to-screen and screen-to-map coordinate conversion
• Bilinear height interpolation for smooth terrain
• Terrain transition bitmask computation (edge + corner)
• Integration with n_astar for pathfinding on the tile grid
• Chunk-based binary map file format (save/load)

Based on:

• GameDev.net Articles 747/748: "Isometric Tile Engine" series
• GameDev.net Article 934: "Terrain Transitions"
• GameDev.net Article 1269: "Axonometric Projections"
• GameDev.net Article 2026: "Height-Mapped Isometric"

Author

Castagnier Mickael

Version

2.0

Date

01/03/2026

Definition in file n_iso_engine.h.