HexWalker

Name

HexWalker -- A Hex that Moves on the Grid

Synopsis


#include <hexmap.h>



struct      HexWalker;
struct      HexWalkerClass;


HexWalker*  hex_walker_new                  (HexData *image);
void        hex_walker_connect_grid         (HexWalker *walker,
                                             HexGrid *grid);
gboolean    hex_walker_set_position         (HexWalker *walker,
                                             gint x,
                                             gint y,
                                             gint depth);
void        hex_walker_get_position         (HexWalker *walker,
                                             gint *x,
                                             gint *y,
                                             gint *depth);
gboolean    hex_walker_move                 (HexWalker *walker,
                                             HexDirectionSimple direction,
                                             gint distance);
void        hex_walker_set_constrain_to_grid
                                            (HexWalker *walker,
                                             gboolean constrain);
gboolean    hex_walker_get_constrain_to_grid
                                            (HexWalker *walker);

Object Hierarchy


  GObject
   +----HexTile
         +----HexObject
               +----HexWalker

Signal Prototypes


"moved"     void        user_function      (HexWalker *hexwalker,
                                            gpointer user_data);

Description

A HexWalker is a HexTile that moves on the grid. As such, it has a definite position on a single grid (unlike either HexTile or HexObject, which can be used at multiple locations on multiple grids at the same time). This is reflected that the function hex_walker_connect_grid() is used to place it on a grid, as opposed to hex_grid_set_tile().

Since a HexWalker has a definite position, it can interact with any HexObject near it in the grid. It does this through a number of class functions. Whenever it moves, through a call to hex_walker_set_position() or hex_walker_move(), the following sequence occurs:

1. It calls its own self_try_move() member function. If this returns FALSE, this sequence stops and the walker doesn't move.

2. It calls the proximity_try_more() function of any "nearby" HexObject, including itself. If any of these functions return FALSE, this sequence stops and the walker doesn't move.

3. Since the move is now certain to take place, it calls the proximity_moved_from() function of any "nearby" HexObject, including itself.

4. It moves

5. It calls the proximity_moved_to() function of any "nearby" HexObject, including itself.

6. It emits the moved signal

A "nearby" HexObject, as mentioned above, is one whose distance in hexes from the HexWalker is less than the proximity attribute of the walker (currently hardcoded to 3, FIXME to allow user setting, can also be set by derived classes). Note that a proximity of 1 would only "see" a HexObject in the walker's own hex, and a proximity of 0 wouldn't see any (even the HexWalker itself).

A call to hex_walker_connect_grid() results in a shortened version of the above sequence, with the calls to self_try_move() and proximity_try_move() ommitted. This is because the *_try_move() functions are called on the walker's current grid, while those on the grid it is moving to are most likely to be relevant.

The idea behind these member functions is to make the entities on the grid derived classed of HexWalker and HexObject which interact in complicated ways. Have fun.

Details

struct HexWalker

struct HexWalker;

A hex that moves on the grid


struct HexWalkerClass

struct HexWalkerClass;

The class structure for HexWalker


hex_walker_new ()

HexWalker*  hex_walker_new                  (HexData *image);

create a HexWalker

image :

a HexData

Returns :

the newly created HexWalker


hex_walker_connect_grid ()

void        hex_walker_connect_grid         (HexWalker *walker,
                                             HexGrid *grid);

Place a HexWalker in a HexGrid. Since, unlike a basic HexTile, a HexWalker occupies a definite position, this function is used instead of hex_grid_set_tile(). This function only fails if there is already a HexObject at the (x, y) and depth coordinates that walker is attempting to occupy.

walker :

a HexWalker

grid :

a HexGrid to connect walker to. Passing NULL disconnects walker from its current grid


hex_walker_set_position ()

gboolean    hex_walker_set_position         (HexWalker *walker,
                                             gint x,
                                             gint y,
                                             gint depth);

Move a HexWalker

walker :

a HexWalker

x :

the new x coordinate of walker

y :

the new y coordinate of walker

depth :

the new depth of walker

Returns :

TRUE if successful, FALSE if not


hex_walker_get_position ()

void        hex_walker_get_position         (HexWalker *walker,
                                             gint *x,
                                             gint *y,
                                             gint *depth);

Get the position of a HexWalker

walker :

a HexWalker

x :

a location to return the x coordinate of walker

y :

a location to return the y coordinate of walker

depth :

a location to return the depth of walker


hex_walker_move ()

gboolean    hex_walker_move                 (HexWalker *walker,
                                             HexDirectionSimple direction,
                                             gint distance);

Move a HexWalker in a particular direction

walker :

a HexWalker

direction :

the direction to move walker

distance :

the distance to move walker

Returns :

TRUE on success, FALSE otherwise


hex_walker_set_constrain_to_grid ()

void        hex_walker_set_constrain_to_grid
                                            (HexWalker *walker,
                                             gboolean constrain);

Set whether a HexWalker is constrained to the interior of its grid.

walker :

a HexWalker

constrain :

TRUE to constrain walker to the interior of its current grid, FALSE to allow it to wander beyond the borders


hex_walker_get_constrain_to_grid ()

gboolean    hex_walker_get_constrain_to_grid
                                            (HexWalker *walker);

Get whether a HexWalker is constrained to the interior of its grid.

walker :

a HexWalker

Returns :

TRUE if walker is constrained to the interior of its current grid, FALSE if it is allowed to wander beyond the borders

Signals

The "moved" signal

void        user_function                  (HexWalker *hexwalker,
                                            gpointer user_data);

The HexWalker just moved to a new hex.

hexwalker :

the object which received the signal.

user_data :

user data set when the signal handler was connected.