The Maps Module¶

These classes have cdefed functions that cannot be read by Sphinx. Read the source if you want to find out more about using them.

This module extends the base functionality of KivEnt by integrating it with the Tiled map editor. See example 14_tmx_loader for a practical demonstration of using these systems.

Tiled Managers¶

If you are using the kivent_maps module, an additional manager will be available to aid in the use of Tiled’s map format.

class kivent_maps.map_manager.MapManager¶

Manages memory allocation and assigment of map data like the TileStructs and ObjStructs.

Attributes:

maps (dict): A dictionary matching names of the map to TileMaps

Attributes (Cython Access Only):

maps_block (MemoryBlock): The memory block which stores the structs for a TileMap.

animation_manager (AnimationManager): instance of the gameworld’s animation_manager to be used by TileMaps for obtaining animation info.

model_manager (ModelManager): instance of the gameworld’s model_manager for obtaining rendering info.

allocation_size (unsigned int): Size of maps_block

load_map()¶

Loads a TileMap object from tiles and objects in the specified list of dicts format. If they aren’t specified it just allocates space in maps_block for the required tile layers amd objects.

Args:

map_size_x (unsigned int): number of rows

map_size_y (unsigned int): number of cols

tiles (list): 3d list of dicts containg data of the tiles. See TileMap for the format. Will not be set in the TileMap if None.

tile_layers (unsigned int): the number of layers.

objects (list): 3d list of dicts containg data of the tiles. See TileMap for the format. Will not be set in the TileMap if None.

object_count (unsigned int): number of objects which would be added

orientation (str): Orientation of the map tiles. Can be one of ‘orthogonal’, ‘staggered’, ‘hexagonal’, ‘isometric’

Systems¶

class kivent_maps.map_system.MapSystem¶: The MapSystem manages a dynamic set of renderers used to display the various labels of the provided tilemap. It will register a new MapManager with Gameworld.reigster_manager that will be used to manage the various data loaded from .tmx files. Each component represents a coordinate for a tile.

class kivent_maps.map_system.MapComponent¶

The component associated with MapSystem.

Attributes:

entity_id (unsigned int): The entity_id this component is currently associated with. Will be <unsigned int>-1 if the component is unattached.

pos (tuple): The coordinate position for this tile on the map.

Utils¶

kivent_maps.map_utils.init_entities_from_map(tile_map, init_entity)[source]¶

Initialise entities for every layer of every tile and add them to the corresponding systems.

Args:

tile_map (TileMap): the tile map from which to load the tiles.

init_entity (function): the gameworld.init_entity function

kivent_maps.map_utils.load_map_systems(layer_count, gameworld, renderargs, animargs, polyargs)[source]¶

Create and initialise the systems required for displaying all layers of the map. Each layer requires a Renderer for images, PolyRenderer for shapes and AnimationSystem for animated tiles.

The name format of the Renderer is map_layer%d, PolyRenderer is map_layer%d_polygons, AnimationSystem is map_layer%d_animator where %d is the layer number.

Args:

layer_count (unsigned int): Number of layers to init

gameworld (Gameworld): Instance of the gameworld

renderargs (dict): Dict of arguments required to init the Renderer. This is same as those used in a KV file for adding a system.

animargs (dict): Dict of arguments required to init the AnimationSystem

polyargs (dict): Dict of arguments required to init the PolyRenderer.

Return:

list of str, list of str: A tuple of two lists of system names with fisrt containing names of Renderers and PolyRenderers and second containing names of AnimationSystems. The names are in the order in which they are added to the Gameworld. You can use these lists for init_gameworld and setup_state.

kivent_maps.map_utils.parse_tmx(filename, gameworld)[source]¶

Uses the tmx library to load the TMX into an object and then calls all the util functions with the relevant data.

Args:

filename (str): Name of the tmx file.

gameworld (Gameworld): instance of the gameworld.

Return:

str: name of the loaded map which is the filename

Map Data¶

class kivent_maps.map_data.HexagonalTileMap¶

HexagonalTileMap is for hexagonal tiles. Hexagonal tiles are like isometric tiles but with an extra flat length along width or height. They are also arranged in the staggered format.

Attributes:: hex_side_length (unsigned int): The side length of the hexagon in the tile. This turns out to be the same as considering an isometric tile lengthened along width/height. The extra length makes one side of the hexagon.

class kivent_maps.map_data.IsometricTileMap¶: IsometricTileMap is used to display isometric tiles in the isometric projection layout. It is a subclass of TileMap with different get_tile_position and size_on_screen.

class kivent_maps.map_data.LayerObject¶

LayerObject is a non-tile object on the map. The types of LayerObject are polygons, ellipses and images. To render a LayerObject we require the render data (model and color/texture) and position.

Attributes:

model (VertexModel): The vertex model to render for this object. If it is a polygon/ellipse this model will contain the vertices data for those shapes.

texture (str): Name of the texture used. This will be set only if the LayerObject is an image else will be None.

position (tuple): Position as (x,y) of the first vertex inside this Object’s VertexModel, x being distance from left-edge and y being distance from top-edge.

layer (unsigned int): Layer in which the object is.

color (tuple): Color of the Object if it is a shape. This color data is taken from the first vertex of its VertexModel.

class kivent_maps.map_data.LayerTile¶

A LayerTile represents data for one layer of a Tile. It stores informtion required to render this layer of the tile.

Attributes:

model (str): Name of the model used by this LayerTile

texture (str): Name of the texture used by this LayerTile

animation (str): Name of the animation used by this LayerTile or None if this LayerTile is not animated.

layer (unsigned int): layer index of this LayerTile.

Attributes: (Cython Access Only)

tile_pointer (TileStruct*): Pointer to a TileStruct which stores data required by the attributes.

model_manager (ModelManager): Instance of the gameworld’s ModelManager to get vertex model pointer from model name.

animation_manager (AnimationManager): Instance of the gameworld’s AnimationManager to get animation data pointer from animation name.

class kivent_maps.map_data.StaggeredTileMap¶

StaggeredTileMap is a subclass of TileMap which is used for isometric staggered tile maps. It overrides the get_tile_position function and size_on_screen property because they are calculated differently for staggered tiles.

Staggered tiles are arranged like this:

---------
 ---------
---------
 ---------

or 

| | | |
|||||||
|||||||
|||||||
|||||||
 | | |

Attributes:

stagger_index (str): indicates whether to shift even or odd tiles while staggering. Can take value ‘even’ or ‘odd.

stagger_axis (boolean): Whether to stagger along x or y axis. Can take values ‘x’ and ‘y’.

class kivent_maps.map_data.Tile¶

A Tile is a collection of LayerTiles for one grid position on the map. The LayerTiles hold data for idividual layers and collectively form one Tile. Multiple Tiles arranged on the grid form the TileMap.

Attributes: (Cython Access Only)

model_manager (ModelManager): Gameworld’s ModelManager instance to pass to LayerTiles while initialising them.

animation_manager (AnimationManager): Gameworld’s AnimationManager instance to pass to LayerTiles while initialising them.

layer_count (unsigned int): The maximum number of layers this Tile can hold i.e. the size of the TileStruct array.

_layers (TileStruct*): Pointer to TileStruct array which holds data for each layer of this tile. Size of this array is given by layer_count.

Attributes:

layers (list): List of LayerTiles contained in this tile. The list only contains a LayerTile for the non-empty layers so the list size may be less than layer_count.

get_layer_tile()¶

Returns a LayerTile object for the given layer.

Args:: layer (unsigned int): The layer for which to return the LayerTile.

class kivent_maps.map_data.TileMap¶

A TileMap holds all tile data for each location of the map grid for each layer, and a list of arbitrarily positioned LayerObjects. The tiles in this TileMap will be orthogonal.

Render data for tiles is stored as a contiguous array of TileStructs. If the map size is M rows, N columns and L layers then the array dimensions are [M][N][L]. Each location (i,j) has a 1D array of size [L] which can be interfaced using Tile object. Each TileStruct inside that 1D array is interfaced using LayerTile.

Attributes:

tiles (list): 2D array of Tile objects representing every grid grid location on the map. To set the tile data provide it a 2D array of a list of dicts in the format

tiles[i][j] =                     [{
            'model': 'model-name',
            'texture': 'texture-name',
            'layer': 1,
        },
        {
            'animation': 'animation-name',
            'layer': 2,
        }]

The ‘layer’ is zero indexed and layers for which there is no dict in this list are left empty.

objects (list): 2D list of LayerObjects on the map, separated by layer. To set data for these pass a 2D list of dicts of the format

objects[layer] =                     [{
            'model': 'model-name',
            'texture': texture-name',
            'position': (x, y)
        }]

z_index_map (list): List of ints which maps layer index of tiles and objects to z index i.e. render order for that layer. While initialising entities from this TileMap use this z_index_map to get which system to add the entity to given the layer index. Values till tile_layer_count correspond to tile layers and after that to object layers.

size (tuple): Size of the grid i.e. (rows, cols)

size_on_screen (tuple): Size in pixels when displayed on the screen

tile_size (tuple): Size in pixels of one tile image

name (str): Name of this TileMap

get_object()¶

Get nth LayerObject in the map from ObjStruct. Because there is no fixed number of objects for each object layer, the objects are one big array and they are referenced by that index. The layer value is stored in the ObjStruct.

Args:

n (unssigned int): index of the object in the list

empty (boolean): Will set NULL to the pointers in the ObjStructs if True. Default False.

Return:

LayerObject: containing data of the ObjStruct

get_tile()¶

Get a Tile at (i,j) grid position of the tile map from TileStruct array

Args:

x (unsigned int): row of the tile

y (unsigned int): col of the tile

empty (boolean): Will set NULL to the pointers in all the TileStructs if True. Default False.

Return:

Tile: contains data of TileStruct array

get_tile_position()¶

Calculates the pixel position of the center of the tile at (i, j) grid position.

Args:

i (unsigned int): row of the tile

j (unsigned int): col of the tile

Return:

(unsigned int, unsigned int): Pixel position of center as x,y where x is distance from left edge and y is from top edge.