Fraser/pico-8-games

{
    # --- Metadata ---
    "cart_id":      str,        # Unique cart identifier (lid)
    "title":        str,        # Game title
    "author":       str,        # Author username
    "description":  str,        # Author's description (when available)
    "tags":         list[str],  # User-applied tags ("platformer", "shooter", etc.)
    "stars":        int,        # Community star/like count (primary quality signal)
    "reply_count":  int,        # Number of thread replies (engagement signal)
    "date_posted":  str,        # Original post date (YYYY-MM-DD HH:MM:SS)
    "date_updated": str,        # Last update date
    "license":      str,        # "CC4-BY-NC-SA" or "" (71% are CC4-licensed)
    "thread_id":    int,        # BBS thread ID
    "thread_url":   str,        # Direct link to the BBS thread

    # --- Code ---
    "lua_code":     str,        # Complete Lua source code
    "token_count":  int,        # Approximate PICO-8 token count
    "char_count":   int,        # Character count of Lua code

    # --- Quality flags ---
    "has_init":     bool,       # Has _init() function
    "has_update":   bool,       # Has _update() or _update60() function
    "has_draw":     bool,       # Has _draw() function
    "is_duplicate": bool,       # Exact code duplicate of a higher-starred cart

    # --- Visual data ---
    "spritesheet":  Image,      # 128x128 RGB spritesheet (PICO-8's 16-color palette)
    "label_image":  Image,      # 128x128 cart label screenshot (if captured by dev)
    "map_image":    Image,      # Rendered tile map using spritesheet (if map data exists)

    # --- Raw data (for lossless roundtripping) ---
    "gfx_hex":      str,        # Raw spritesheet as hex digits
    "map_data":     list[int],  # Raw tile indices (uint8)
    "sprite_flags": list[int],  # Raw sprite flags (uint8)
    "sfx_hex":      str,        # Raw sound effect data
    "music_hex":    str,        # Raw music pattern data
}

from datasets import load_dataset

ds = load_dataset("Fraser/pico-8-games")

# Browse the top games
top = ds["train"].sort("stars", reverse=True)
for row in top.select(range(10)):
    print(f"{row['title']:30s}  {row['stars']:4d} stars  by {row['author']}")

# Filter to high-quality, unique, CC4-licensed games
hq = ds["train"].filter(lambda x: (
    x["stars"] >= 10
    and not x["is_duplicate"]
    and x["has_init"] and x["has_update"] and x["has_draw"]
    and x["license"] == "CC4-BY-NC-SA"
))
print(f"High-quality subset: {len(hq)} games")

row = ds["train"][0]

# Build the .p8 file from dataset columns
p8_text = "pico-8 cartridge // http://www.pico-8.com\nversion 42\n"
p8_text += f"__lua__\n{row['lua_code']}\n"
p8_text += f"__gfx__\n{row['gfx_hex']}\n"

# Add map data (convert byte array back to hex lines)
map_bytes = row["map_data"]
if map_bytes:
    p8_text += "__map__\n"
    for y in range(0, len(map_bytes), 128):
        line = "".join(f"{b:02x}" for b in map_bytes[y:y+128])
        p8_text += line + "\n"

# Add sprite flags
flags = row["sprite_flags"]
if flags:
    p8_text += "__gff__\n"
    p8_text += "".join(f"{b:02x}" for b in flags) + "\n"

p8_text += f"__sfx__\n{row['sfx_hex']}\n"
p8_text += f"__music__\n{row['music_hex']}\n"

with open("game.p8", "w") as f:
    f.write(p8_text)
# Then: pico8 -run game.p8

# The spritesheet is already a PIL Image
row = ds["train"][0]
row["spritesheet"].save("sprites.png")

# Or parse individual 8x8 sprites from the hex data
gfx = row["gfx_hex"]
lines = gfx.strip().split("\n")
# Each hex digit = one pixel (4-bit color index)
# Sprite 0 is at (0,0), sprite 1 at (8,0), ..., sprite 16 at (0,8)
sprite_id = 42
sx = (sprite_id % 16) * 8
sy = (sprite_id // 16) * 8
for y in range(8):
    row_pixels = lines[sy + y][sx:sx + 8]
    print(row_pixels)  # e.g. "00770700" — each digit is a color index

import numpy as np
from PIL import Image

PICO8_PALETTE = [
    (0,0,0), (29,43,83), (126,37,83), (0,135,81),
    (171,82,54), (95,87,79), (194,195,199), (255,241,232),
    (255,0,77), (255,163,0), (255,236,39), (0,228,54),
    (41,173,255), (131,118,156), (255,119,168), (255,204,170),
]

row = ds["train"][0]
map_data = row["map_data"]  # flat list of uint8 tile indices
# Reshape to 32 rows x 128 columns (some carts use 64 rows, sharing sprite memory)
width = 128
height = len(map_data) // width
tiles = np.array(map_data).reshape(height, width)

print(f"Map size: {width}x{height} tiles = {width*8}x{height*8} pixels")
print(f"Unique tiles used: {len(np.unique(tiles))}")

row = ds["train"][0]
sfx_lines = row["sfx_hex"].strip().split("\n")

for i, line in enumerate(sfx_lines[:4]):  # First 4 SFX
    # First 2 chars: editor mode, next 2: speed, next 2: loop start, next 2: loop end
    header = line[:8]
    notes = line[8:]
    speed = int(header[2:4], 16)
    print(f"SFX {i}: speed={speed}, {len(notes)//5} notes")
    # Each note is 5 hex chars: pitch(2) waveform(1) volume(1) effect(1)

row = ds["train"][0]
music_lines = row["music_hex"].strip().split("\n")

for i, line in enumerate(music_lines[:8]):
    # Each line: 2 flag chars + 4 channel values (2 hex chars each)
    flags = int(line[0:2], 16)
    channels = [int(line[2+j*2:4+j*2], 16) for j in range(4)]
    # Bit 0-2 of each channel byte: loop flags; bits 6+: SFX index (0-63, 65+ = off)
    ch_display = [f"sfx {c & 0x3f}" if c < 65 else "---" for c in channels]
    print(f"Pattern {i}: {' | '.join(ch_display)}  flags={flags:08b}")

@dataset{pico8games2026,
  title={PICO-8 Games Dataset},
  author={Fraser Greenlee},
  year={2026},
  url={https://huggingface.co/datasets/Fraser/pico-8-games},
  note={10,967 PICO-8 cartridges from the Lexaloffle BBS}
}