pyxen.GridMap

A GridMap is a spatial container made of cells arranged in rows and columns.

It defines the tile layout, cell size, optional tile atlas, and the collision space for GridBody.

For collision concepts, see Collision.

Constructor

GridMap(
    *,
    rows=None,
    columns=None,
    size=None,
    image=None,
    tilemap=None
)

All parameters are keyword-only.

Parameters

Example

level_map = GridMap(
    rows=10,
    columns=16,
    size=(16, 16),
    image="tileset"
)

Loading from a .tilemap asset

A .tilemap asset (created in the built-in Tilemap editor) stores the grid dimensions, cell size, tileset image, and every painted tile with an optional collision tag. Pass its name — without the extension — to tilemap= and all four geometry parameters plus every cell is preloaded automatically:

# Editor produced Assets/level1.tilemap
level = world.spawn(map=GridMap(tilemap="level1"))

Explicit rows/columns/size/image still win over values read from the asset, so the same tilemap can back a smaller debug view:

# Test with a 4×4 preview of the same tilemap
preview = GridMap(tilemap="level1", rows=4, columns=4)

When the dimensions are overridden the preloaded cells are discarded — the grid starts empty and you can paint it with map.set() as usual.

Attaching a GridMap

During spawn:

level = world.spawn(
    map=GridMap(
        rows=10,
        columns=16,
        size=(16, 16),
        image="tileset"
    )
)

Or later:

entity = world.spawn()
entity.map = GridMap(rows=8, columns=8, size=(16, 16))

Properties

map.active

Controls whether collision simulation runs for this map. When False, no body movement, collisions, or callbacks are processed for any GridBody attached to this map.

# Pause collisions (e.g. pause menu)
level.map.active = False

# Resume collisions
level.map.active = True

Modifying Tiles

Use map.set() to configure tiles.

map.set(
    row=0,
    column=1,
    tile=(tile_column, tile_row),
    tag=optional_tag
)

Parameters

Example: Set a Tile

level.map.set(
    row=2,
    column=5,
    tile=(3, 1)
)

Example: Add Collision Tag

level.map.set(
    row=4,
    column=2,
    tile=(0, 0),
    tag=1  # wall
)

Grid Coordinates

• Rows increase vertically
• Columns increase horizontally

Indices outside bounds are safely ignored.

GridMap + GridBody

A GridBody interacts with the GridMap for collision, movement resolution, and trigger detection.

GridBody must be a child of the GridMap entity.

level = world.spawn(
    map=GridMap(
        rows=8,
        columns=8,
        size=(16, 16),
        image="tiles"
    )
)

player = world.spawn(
    body=GridBody(),
    parent=level
)

Minimal Example: Basic Level

level = world.spawn(
    map=GridMap(
        rows=8,
        columns=8,
        size=(16, 16),
        image="tiles"
    )
)

# Create floor
for r in range(8):
    for c in range(8):
        level.map.set(row=r, column=c, tile=(0, 0))

# Create walls
for c in range(8):
    level.map.set(row=0, column=c, tile=(1, 0), tag=1)
    level.map.set(row=7, column=c, tile=(1, 0), tag=1)

Tags

tag is optional metadata per tile.

Typical uses:

• 0 — empty
• 1 — wall
• 2 — water
• 3 — damage zone

Tags are interpreted by your gameplay or collision system.

Mini samples

Open from Samples & Tutorials inside Pyxen:

• GridMap(tilemap=…) — Load a tilemap asset (size, image, tiles, tags).
• map.set() — Paint tiles programmatically.
• map.wrap_x — Self-wrapping world. Camera pans to show the seam.
• map.hit() — Query whether a tagged tile overlaps a rectangle.