Module pico8 

Importing PICO-8 cartridge assets.

Pixel8 is a loving homage to PICO-8: it borrows the very same 16-color palette, the same eight chip-tune waveforms and per-step effects, and the same 128x128 sprite sheet and 16-wide sprite layout. That overlap means a PICO-8 cart’s assets — graphics, sprite flags, map, sound effects and music — transfer into a Pixel8 project almost one-to-one. This module does exactly that.

Only the assets are imported. PICO-8 games are written in Lua and Pixel8 games in Rust, so the cart’s code is ignored entirely: the new project gets a stub src/lib.rs to build against, and the game logic is yours to write in Rust against the imported art and audio.

Two input formats are understood:

• .p8 — the plain-text cartridge: labelled __gfx__, __gff__, __label__, __map__, __sfx__ and __music__ sections of hex (the __lua__ section is skipped).
• .p8.png — the PNG cartridge: the game’s 32 KiB ROM hidden two bits at a time in the low bits of each pixel’s A/R/G/B channels. The image is decoded, the ROM reassembled, and the same fixed memory map PICO-8 uses (0x0000 gfx, 0x2000 map, 0x3000 flags, 0x3100 music, 0x3200 sfx) is read out.

Structs

Placement

Where one kind’s appended items landed in the destination.

Report

The outcome of an append: where each kind landed, plus any warnings (e.g. references left pointing at slots that were not part of the selection).

Selection

Which source assets to append into a destination cart. Indices are the source PICO-8 cart’s own indices (sprite 0..256, SFX/music 0..64).

Constants

IMPORT_TEMPLATE

Stub src/lib.rs scaffolded for an imported cart. The assets are real; the game logic is the user’s to write in Rust.

Functions

append_pico8_assets

Append the selected src assets into dest, after dest’s last used slot of each kind. Imported audio cross-references (music channels and SFX custom-instrument notes) are remapped to the slots their targets landed in; references to slots that were not selected are left as-is and reported as warnings. dest is only mutated on success (a capacity or validation error leaves it untouched).

default_dir_name

Default project directory name to import a cart into when none is given: the cart’s name with its suffixes peeled off (airwolf.p8 -> airwolf), falling back to imported.

import_project

Create a new Pixel8 project from a PICO-8 cart’s assets.

parse_bytes

Read a PICO-8 cart’s assets from raw bytes, auto-detecting the format.

parse_clipboard

Decode a PICO-8 editor clipboard string. Recognises [gfx] and [sfx] blobs; anything else is an error.

parse_file

Read a PICO-8 cart’s assets from a file, auto-detecting .p8 text vs .p8.png.