Skip to content

pixel-level-description.md

Latest commit

 

History

History
128 lines (87 loc) · 3.86 KB

pixel-level-description.md

File metadata and controls

128 lines (87 loc) · 3.86 KB

Picross Binary Level Format Specification (Structure Only)

File Extension: .pxl Endianness: Little-Endian String Encoding: UTF-8 Palette Dependency: External (Global Game Palette)

1. Overview

This format stores the level data for a Picross game. It relies on the Game Engine to provide the color definitions.

  • Logic Layer: Defines the puzzle rules (Bitmask).
  • Art Layer: Defines the visual outcome (Color Indices).
  • Colors: The file contains no color data and no palette references. The game engine applies its current global palette to the indices found in the Art Layer.

2. File Structure Map

The file is read as a continuous stream of bytes.

Sequence Section Size (Bytes) Content
1 Header 9 Signature, Version, Width, Height.
2 Metadata 1 + N Description string length + characters.
3 Logic **** Bitmask (1 bit per pixel).
4 Art **** Byte-map (1 byte per pixel).

3. Detailed Segment Specification

I. Header (9 Bytes)

Contains the validation signature and grid dimensions.

Offset Type Name Description
0x00 char[4] Signature Fixed value: PCRS. Used to verify file type.
0x04 uint8 Version Format version. Current: 3.
0x05 uint16 Width Grid Width ().
0x07 uint16 Height Grid Height ().

II. Metadata (Variable)

A simple length-prefixed string for the level title.

  • Length (uint8): Number of characters in the string.
  • Text (char[]): The UTF-8 string.

III. Logic Layer (Bitpacked)

The "Answer Key". Describes whether a cell is logically filled or empty to generate the puzzle hints.

  • Data Type: Bitmask.
  • Formula: Total Logic Bytes =
  • Mapping:
  • Bit 0: Empty / Background (Non-interactive).
  • Bit 1: Filled (Interactive part of the puzzle).

Optimization: Pixels are packed 8 per byte. If is not divisible by 8, the last byte is padded with zeroes.

IV. Art Layer (Byte Map)

The "Visual Reward". Describes which index of the Global Palette to use for each pixel.

  • Data Type: Array of uint8.
  • Size: Exactly bytes.
  • Mapping: Each byte is an integer .

4. Integration Logic (How the Game Reads It)

Since the file has no colors, the Game Engine acts as the "renderer".

Scenario:

  • Game Engine: Has a Global Palette where Index 5 = "Bright Gold".
  • File (star.pxl):
  • Grid position [2,2] has Logic Bit = 1.
  • Grid position [2,2] has Art Byte = 5.

Step-by-Step Execution:

  1. Load: Game reads star.pxl.
  2. Play: User calculates hints based on the Logic Bit (1). User clicks the cell.
  3. Feedback: The move is correct (matches Logic).
  4. Render: The game looks at the Art Byte (5).
  5. Display: The game retrieves color 5 from the Global Palette ("Bright Gold") and paints the cell.

5. Implementation Example (Pseudocode)

struct PicrossLevel {
    int Width;
    int Height;
    string Description;
    bool[] LogicMap; // Created from bits
    byte[] ArtMap;   // Created from bytes
}

PicrossLevel LoadLevel(BinaryReader reader) {
    // 1. Header (9 Bytes)
    if (reader.ReadString(4) != "PCRS") Error();
    byte version = reader.ReadByte();
    ushort w = reader.ReadUInt16();
    ushort h = reader.ReadUInt16();

    // 2. Meta
    byte nameLen = reader.ReadByte();
    string name = reader.ReadString(nameLen);

    // 3. Logic (Bits)
    int totalPixels = w * h;
    int logicBytes = (int)Math.Ceiling(totalPixels / 8.0);
    byte[] rawBits = reader.ReadBytes(logicBytes);
    bool[] logicMap = UnpackBits(rawBits, totalPixels);

    // 4. Art (Bytes)
    byte[] artMap = reader.ReadBytes(totalPixels);

    return new PicrossLevel(w, h, name, logicMap, artMap);
}