<-- Back to AG_Intro.3

SYNOPSIS

#include <agar/core.h>
#include <agar/map.h>

DESCRIPTION

The MAP interface implements a two-dimensional map of fixed-size tiles, which are stacks of elements Element types include:

MAP_ITEM_TILE	Pointer to a RG_Tile(3).
MAP_ITEM_ANIM	Pointer to a RG_Anim(3).
MAP_ITEM_WARP	Pointer to some other node, possibly on another map. This is commonly used by MAP_Actor(3) objects.

Graphical elements define two displacements in pixels of the image from the tile's origin, the centering offset and the motion offset.

The centering offset is typically assigned by a level designer, and the motion offset is for animation purposes. If the map is drawn scaled, the centering offset is scaled to the tile size, but the motion offset is not.

Graphical elements provide the renderer with a list of graphical transformations that should be applied before the tile is drawn (the resulting tile is cached). A per-element layer attribute also defines the attributed layer.

INHERITANCE HIERARCHY

AG_Object(3)-> MAP.

INITIALIZATION

MAP * MAP_New (void *parent, const char *name)

int MAP_AllocNodes (MAP *map, Uint w, Uint h)

void MAP_FreeNodes (MAP *map)

void MAP_SetZoom (MAP *map, int camera, Uint factor)

MAP_New() allocates, initializes and attaches a new map.

The MAP_AllocNodes() function allocates w x h nodes, assuming that no node is currently allocated. MAP_AllocNodes() returns 0 on success or -1 on failure. The maximum allowable geometry is defined by MAP_WIDTH_MAX and MAP_HEIGHT_MAX. The MAP_FreeNodes() function releases the nodes allocated by map.

The MAP_Resize() function reallocates the nodes arrays, initializing the new nodes and freeing the excess ones. MAP_Resize() returns 0 on sucess or -1 on failure.

The MAP_SetZoom() function sets the zoom factor for a given map view. Actors are displayed to this scale.

NODE INITIALIZATION

void MAP_NodeInit (MAP_Node *node)

int MAP_NodeLoad (MAP *map, AG_DataSource *ds, MAP_Node *node)

void MAP_NodeSave (const MAP *map, AG_DataSource *ds, const MAP_Node *node)

void MAP_NodeDestroy (MAP *map, MAP_Node *node)

The MAP_NodeInit() function initializes a node. The MAP_NodeDestroy() function frees resources allocated by a node (such as the item stack). To reinitialize a node, this function must be followed by MAP_NodeInit().

The MAP_NodeLoad() function loads a node from ds, returning 0 on success or -1 on failure. MAP_NodeSave() saves a node to ds.

MAP ITEMS

void MAP_ItemInit (MAP_Item *r)

void MAP_ItemSetCenter (MAP_Item *r, int xcenter, int ycenter)

void MAP_ItemSetMotion (MAP_Item *r, int xmotion, int ymotion)

void MAP_ItemSetTile (MAP_Item *r, MAP *m, RG_Tileset *ts, Uint32 tileID)

void MAP_ItemSetAnim (MAP_Item *r, MAP *m, RG_Tileset *ts, Uint32 animID)

void MAP_ItemSetLayer (MAP_Item *r, int layer)

void MAP_ItemDestroy (MAP *map, MAP_Item *r)

The MAP_ItemInit() function initializes a node element structure.

The MAP_ItemSetCenter() function sets the centering offset of a graphical element. MAP_ItemSetMotion() sets the motion offset of a graphical element.

The functions MAP_ItemSetTile() and MAP_ItemSetAnim() associate a new tile or animation to the element r (of type MAP_ITEM_TILE or MAP_ITEM_ANIM).

The MAP_ItemSetLayer() function associates the graphical element r with the given layer. The layer does not need to exist; the element will not be visible if that is the case.

The MAP_ItemDestroy() function frees the resources reserved by a node element. It must be followed by MAP_ItemInit to reinitialize the node element structure.

NODE MANIPULATIONS

void Fo MAP_NodeMoveItem"MAP *src_map" "MAP_Node *src_node" "MAP_Item *src_r" "MAP *dst_map" "MAP_Node *dst_node" "int dst_layer" Fc
MAP_Item * Fo MAP_NodeCopyItem"const MAP_Item *src_r" "MAP *dst_map" "MAP_Node *dst_node" "int dst_layer" Fc
void MAP_NodeDelItem (MAP *map, MAP_Node *node, MAP_Item *r)

MAP_Item * MAP_NodeAddTile (MAP *map, MAP_Node *node, RG_Tileset *ts, Uint32 tileID)

MAP_Item * MAP_NodeAddAnim (MAP *map, MAP_Node *node, RG_Tileset *ts, Uint32 animID)

MAP_Item * Fo MAP_NodeAddWarpPoint"MAP *map" "MAP_Node *dst_node" "const char *targetMap" "int x" "int y" "Uint8 dir" Fc

The MAP_NodeMoveItem() function moves src_r from src_node to the node at specific map coordinates and returns 0, or -1 if the coordinates are outside of dst_map. The element is associated with the layer dlayer, unless it is -1.

The MAP_NodeCopyItem() function inserts a copy of src_r on top of dst_node, and associate with dst_layer (unless it is -1).

The MAP_NodeDelItem() function detaches and destroys the given node element.

The MAP_NodeAddTile() function creates a graphical element (a reference to a RG_Tile(3)), where tileID is a tile name (an index into the tiletbl of a RG_Tileset(3)).

The MAP_NodeAddAnim() function creates an animation element (a reference to a RG_Anim(3)), where animID is an animation name (an index into the animtbl of a RG_Tileset(3)).

MAP_NodeAddWarpPoint() Creates a warp point, where targetMap is the pathname of the destination map (as returned by AG_ObjectCopyName()), and the x, y and dir arguments describe the initial position and direction of the object (whatever it may be) in the destination map.

ACTORS

void MAP_AttachActor (MAP *map, MAP_Actor *actor)

void MAP_DetachActor (MAP *map, MAP_Actor *actor)

MAP_AttachActor() attaches the given actor to the map. An object dependency is automatically created, and the map operation of the actor is invoked. This operation is usually responsible for inserting tiles onto the map.

MAP_DetachActor() detaches the given actor from the map. Any pending timer events related to the actor are cancelled, tiles related to the actor are removed and the object dependency is removed.

See MAP_Actor(3) for more information.

HISTORY

The MAP class first appeared in Agar 1.0.