DiscreteMap serialization via bytes #293

New issue

Closed

opened 2026-03-08 20:18:54 +00:00 by john · 0 comments

john commented

2026-03-08 20:18:54 +00:00

Owner

Summary

Enhance DiscreteMap with bytes-based serialization and state count awareness, making it the universal primitive for grid-shaped data with a small number of discrete states.

Motivation

DiscreteMap already represents 2D arrays of discrete values tied to grid dimensions. Multiple systems need to persist and transfer this kind of data:

TileLayer content — save/load tile configurations
Walkable/transparent maps — grid gameplay data
Entity perspective (discovered/visible/unknown) — fog of war state
Game-specific invisible data — any grid-shaped metadata

All of these are arrays with far fewer than 255 states whose dimensions match a grid's width × height. A unified serialization format avoids per-system bespoke solutions.

Proposed API

# State count is known at creation
dmap = mcrfpy.DiscreteMap(width=50, height=50, num_states=3)

# Serialize to bytes (row-major, one byte per cell)
data: bytes = dmap.to_bytes()

# Deserialize from bytes (validates length = w * h)
dmap.from_bytes(data)

# Or construct from bytes directly
dmap2 = mcrfpy.DiscreteMap(width=50, height=50, num_states=3, data=saved_bytes)

Design notes

One byte per cell (uint8) — sufficient for all current use cases (walkable has 2 states, fog has 3, tile layers have <256 terrain types)
num_states enables validation on set operations and could enable future bit-packing optimization (e.g., 2-state maps → 1 bit per cell)
to_bytes() / from_bytes() use Python bytes objects — trivially writable to files, sendable over network, storable in save game dicts
Dimensions are intrinsic to the DiscreteMap, so serialized data is just the flat cell array — the caller tracks which grid it belongs to

Relation to other issues

#252 (Grid/GridView overhaul): DiscreteMap becomes the backing store for grid layers, walkable/visible maps, and entity perspective
Entity.gridstate as DiscreteMap (planned): depends on this serialization capability for save/restore workflows

## Summary Enhance `DiscreteMap` with `bytes`-based serialization and state count awareness, making it the universal primitive for grid-shaped data with a small number of discrete states. ## Motivation DiscreteMap already represents 2D arrays of discrete values tied to grid dimensions. Multiple systems need to persist and transfer this kind of data: - **TileLayer content** — save/load tile configurations - **Walkable/transparent maps** — grid gameplay data - **Entity perspective** (discovered/visible/unknown) — fog of war state - **Game-specific invisible data** — any grid-shaped metadata All of these are arrays with far fewer than 255 states whose dimensions match a grid's width × height. A unified serialization format avoids per-system bespoke solutions. ## Proposed API ```python # State count is known at creation dmap = mcrfpy.DiscreteMap(width=50, height=50, num_states=3) # Serialize to bytes (row-major, one byte per cell) data: bytes = dmap.to_bytes() # Deserialize from bytes (validates length = w * h) dmap.from_bytes(data) # Or construct from bytes directly dmap2 = mcrfpy.DiscreteMap(width=50, height=50, num_states=3, data=saved_bytes) ``` ### Design notes - One byte per cell (uint8) — sufficient for all current use cases (walkable has 2 states, fog has 3, tile layers have <256 terrain types) - `num_states` enables validation on set operations and could enable future bit-packing optimization (e.g., 2-state maps → 1 bit per cell) - `to_bytes()` / `from_bytes()` use Python `bytes` objects — trivially writable to files, sendable over network, storable in save game dicts - Dimensions are intrinsic to the DiscreteMap, so serialized data is just the flat cell array — the caller tracks which grid it belongs to ## Relation to other issues - #252 (Grid/GridView overhaul): DiscreteMap becomes the backing store for grid layers, walkable/visible maps, and entity perspective - Entity.gridstate as DiscreteMap (planned): depends on this serialization capability for save/restore workflows