sgdk-assets

SGDK assets

Turn source art into SGDK resources without surprising the artist or exceeding the console's budgets.

Start with the project

1. Find its .res files, source art, build instructions and toolchain configuration. Preserve the original art and any palette ordering. Work on derived exports when conversion is needed.
2. Use the project's image. Otherwise use ewrogers/sgdk:latest. It supports Linux ARM64 and AMD64; Docker supplies Linux containers on macOS and Windows too. Do not force --platform unless testing another architecture.
3. Read the installed manual before adding or changing a resource declaration. Use /opt/sgdk/bin/rescomp.txt, the matching headers in /opt/sgdk/inc, and examples in /opt/sgdk/sample. Verify symbol names and signatures there before writing C. An API from another SGDK version is not evidence.

Run docker run --rm IMAGE cat /opt/sgdk/bin/rescomp.txt, replacing IMAGE with the chosen image. Commands run as argument arrays from automation. Avoid building shell command strings from asset filenames.

Import workflow

1. Decide how the asset is used: a moving character, background, scrolling map, font, music or sample. Choose the matching ResComp resource rather than treating everything as a sprite.
2. Agree on frame dimensions, palette ownership, transparency and animation layout. Show a preview when possible. Do not silently quantize colors, resize, crop, reorder palette indices or rewrite source files.
3. Make a small .res change. Keep resource names valid C identifiers and paths relative to that .res file. Check exact options in the manual.
4. Build in the container. Use docker run --rm --pull=always --mount "type=bind,source=PROJECT,target=/workspace" IMAGE, replacing PROJECT with the absolute project directory. PowerShell and POSIX shells both support this quoted mount argument. Use sgdk-project if installed for project creation or broader build setup.
5. Fix the first resource error, then rebuild. Inspect the generated header and ResComp's resource totals. Consult importing.md for common causes and costs.
6. Test the ROM in an emulator. Check colors, transparency, frame order, sprite dropout and scrolling. A successful build proves conversion and linking, not visual correctness or 60 Hz performance.

Guardrails

• Separate hardware limits, SGDK implementation choices and game policy when explaining a restriction. Refer to the budget table in the reference.
• Count used pixel indices and per-tile palette needs. A PNG's palette table can contain unused entries; its table length alone does not prove an invalid image.
• Budget shared palettes, resident tile patterns, decompression/upload work and scanline sprite pressure. Standard 8 by 8 patterns have 2048 theoretical addresses; tables and SGDK reservations leave less room for art. Check the actual allocated range before uploads. SGDK logical sprites may contain several hardware sprites. Compression saves ROM; it does not make the decoded tiles free in VRAM.
• Prefer preparing and loading shared data once. Do not decompress images, reload whole palettes or recreate sprites each update without a measured reason. Use SGDK's supported DMA/VBlank flow and check allocation failures.
• Keep generated assembly, headers, objects and ROMs out of source control unless the project explicitly needs them. Retain the authored .res, source exports and asset license/provenance.
• For audio, inspect the selected driver's documentation and the WAV, XGM or XGM2 declarations in the installed manual. Do not mix driver-specific resources or assume every WAV rate and channel layout is accepted. Audio conversion succeeding does not prove playback quality.

Small verified example

assets/import-example is a standalone resource project with an indexed background, two-frame sprite and generated resource types used by C. Copy it to a writable project directory before building. Its README explains the layout and proof limits. For unfamiliar options, build this small case before changing a large asset pipeline.

Report what changed, which image and resource declarations were used, build results, relevant budget changes and anything still needing visual or audio review. Do not claim that estimated totals are measured runtime usage.