Console Graphics skill

console-graphics

The Graphics Artist works on what the player sees. Textures: find them on the extracted disc (loose .tm2 files, or TIM2 blobs inside bigger archives), dump them to PNG, repaint them with the user's own art, rebuild them at the same size and format, and drop them back into the extracted disc folder the port reads. Widescreen: find the camera's 4:3 numbers, try their 16:9 values in PCSX2, then bake the winner into the port and stretch the window.

Be plain about the limits. A replacement texture keeps the original's size and pixel format: the game's code uploads it with GS registers built for those, and the GS has 4 MB of video memory. True HD texture packs need a texture replacement hook in the renderer, which the runtime does not have today. Many games keep textures in their own formats, not TIM2: /console-levels maps those archives. Widescreen is a candidate hunt, not a lookup.

${CLAUDE_SKILL_DIR} below is this skill's folder (where this SKILL.md lives).

python3 "${CLAUDE_SKILL_DIR}/tim2.py" info  console/disc/DATA/TITLE.TM2                      # pictures, formats, GS TEX0
python3 "${CLAUDE_SKILL_DIR}/tim2.py" topng console/disc/DATA --out console/textures/png     # every .tm2 under a folder
python3 "${CLAUDE_SKILL_DIR}/tim2.py" frompng console/disc/DATA/TITLE.TM2 my_title.png --out console/textures/new/TITLE.TM2
python3 "${CLAUDE_SKILL_DIR}/tim2.py" scan  console/disc/DATA/PACK.BIN --extract console/textures/found
python3 "${CLAUDE_SKILL_DIR}/tim2.py" insert console/disc/DATA/PACK.BIN --offset 0x1A2000 --tm2 new.tm2 --out console/textures/new/PACK.BIN
python3 "${CLAUDE_SKILL_DIR}/widescreen.py" scan SLUS_203.12 --out console/patches/widescreen-try.pnach
python3 "${CLAUDE_SKILL_DIR}/widescreen.py" values --fov 60                           # 4:3 -> 16:9 table, Hor+ FOV
python3 "${CLAUDE_SKILL_DIR}/gspacket.py" dma console/dumps/ram.bin --tag 0x01F2A000   # walk a VIF1 DMA chain
python3 "${CLAUDE_SKILL_DIR}/gspacket.py" gif console/dumps/ram.bin --addr 0x00403C10 --length 4096

Other flags: topng --rgba (RGBA instead of palette PNGs), --palette N, --all-palettes, --mips; frompng --quantize (median cut when the art has too many colours), --picture N, --keep-mips, --force; --json on info, scan and widescreen.py.

What it reads and writes

file	what
the extracted disc folder (next to the ELF)	read: .tm2 files and archives that hold TIM2 blobs
console/textures/png/	the dumped PNGs: the user's working copies, never published
console/textures/new/	rebuilt .tm2 files and archives, same size as the originals
the game's main ELF	read by widescreen.py
console/patches/widescreen-try.pnach	one [section] per widescreen candidate, to toggle in PCSX2
console/dumps/*.bin	raw guest RAM dumps that gspacket.py reads (game data: never published)

How the port draws

• The game's own code builds GIF packets and DMA chains as on a PS2. ps2xRuntime/src/lib/gs/gs_frontend.cpp (class GS) takes the packets and register writes, gs/ps2_gif_arbiter.cpp orders the GIF paths, gs/ps2_gs_memory.cpp holds the 4 MB of GS memory, and gs/gs_cpu_backend.cpp (GSCpuBackend) rasterises sprites, triangles and lines in software, sampling textures and CLUTs from that memory.
• Each frame, ps2_runtime.cpp copies the displayed frame (640x448 by default) into a raylib texture and draws it scaled to fit the window, keeping its shape (DrawTexturePro).
• Desktop builds have a debug panel (ps2_debug_panel.cpp, toggled with F1): the GS tab shows the GS registers and draw history, the File/CD tab shows which disc files the game has open, which is how you learn which file a texture comes from.

Textures: the method

1. Find them. tim2.py info on loose .tm2 files. For archives, tim2.py scan <file> --extract DIR finds TIM2 blobs and their offsets. No hits: the game uses its own format; watch the File/CD tab when the texture appears, and hand the file to /console-levels.
2. Dump. tim2.py topng <file or folder> --out console/textures/png. Indexed textures become palette PNGs (exact indices kept); the PS2's alpha (0x80 = opaque) becomes 0xFF; CSM1 palette swizzle is undone.
3. Repaint with the user's own art at the SAME width and height. Keep an indexed texture within its palette size (16 or 256 colours) in the editor, or use --quantize. Untouched pixels stay byte-identical.
4. Rebuild. tim2.py frompng <original.tm2> <edited.png> --out .... The header and GS registers are copied unchanged; mip levels are regenerated from the new art (or kept with --keep-mips). For a blob in an archive: tim2.py insert (same offset, same size; never in place without --force).
5. Drop it in. Back up the original, then put the new file in the extracted disc folder next to the ELF (the runtime's cdRoot): no ISO rebuild. Boot the port (/console-tester) and look.

Format details (headers, CLUT swizzle, alpha, mipmaps): reference/tim2-format.md.

Widescreen: the method

1. widescreen.py scan <ELF> --out console/patches/widescreen-try.pnach lists every 4:3 constant (1.3333334, 0.75, 640/448, 512/448 ...) in data and in lui/ori/mtc1 code, each with the 16:9 value (1.7777778, 0.5625, x4/3 or x3/4) and its pnach line(s). It cannot know which is the camera.
2. In PCSX2, copy the sections into the game's pnach (/console-mod pnach.py crc names it) and enable ONE at a time. The right one widens the view (more on the sides) instead of stretching it. Some games need two (projection and culling); menus and HUDs may need their own.
3. Bake the winner in with /console-mod (pnach.py toml for code, pnach.py override for data).
4. Stretch the port's output to 16:9: the presenter in ps2_runtime.cpp keeps the frame's shape, so the window must be told to show it 16:9 wide. Exact steps and the FOV rules: reference/widescreen.md.

Black screen or garbage: read the packets

When the port runs but draws nothing, or draws noise, look at what the game actually sends before touching the renderer.

1. Get a RAM dump of the moment it goes wrong: 32 MB of RDRAM from guest address 0 (no --base needed). From the port, write runtime.memory().getRDRAM() to console/dumps/ram.bin from a game override (/console-mod override.py new --wrap on the function that kicks the DMA); from PCSX2, its debugger's memory tools or PCSX2-MCP's memory read. A smaller dump works too: pass its start address with --base.
2. Find the chain. The port's debug panel (F1), DMA/IO tab, shows VIF1_TADR and GIF_TADR: the address of the next DMA tag. In PCSX2, a write breakpoint on D1_CHCR (0x10009000) stops where the game starts it.
3. Walk it. gspacket.py dma <dump> --tag <TADR> lists every tag (cnt, next, ref, call, ret, end), decodes the data as a VIF1 stream (UNPACK sizes follow the runtime's own interpreter, STCYCL included), and the GIF packets inside every DIRECT block. --channel gif for PATH3 chains, --verbose for every GS register write, --json to keep it.
4. Read the issues at the bottom. A chain that loops or leaves RAM, an unknown VIF code (the stream is corrupt or decoded from the wrong place), a command cut off mid-stream, an image upload shorter or longer than its BITBLTBUF/TRXREG (a broken texture), a prohibited primitive. Exit 1 means at least one error. The TEX0 and FRAME fields it prints say which texture and which framebuffer a draw uses.
5. Then decide the layer. Dump the same moment in PCSX2 and compare (/console-tester abdiff.py mem). Same packets as PCSX2 but a wrong picture: the runtime draws them wrong (gs/gs_frontend.cpp, gs/gs_cpu_backend.cpp, ps2_vif1_interpreter.cpp), a /console-backend fix. Different packets: something upstream (a stub returning the wrong value, a missing function) fed the game bad data, so /console-tester triage first.

This replaces the base skill's vif_gif_surgeon.py, which decodes one DMA tag and its two VIF codes (and swaps MSCALF and MSCNT).

Guard rails

1. Bring your own game. Only a game the user owns, dumped from their own disc. Never download or look for ISOs, ELFs, BIOS files or texture packs made from other people's dumps, never ask for them.
2. Nothing from the game gets published. The game's textures, the dumped PNGs and the rebuilt .tm2 files stay on the user's machine. Share only the user's OWN art (and the pnach/override for widescreen), never the game's textures, not even edited ones.
3. Not affiliated with Sony. PlayStation is a trademark of Sony Interactive Entertainment.
4. Never overwrite a disc file without a backup; the tools write new files and refuse to overwrite without --force. Same size and format, always.

Hands off to

• /console-levels for archives that are not TIM2 and for repacking them.
• /console-mod to bake a widescreen or camera fix into the port.
• /console-physics for FOV values that are not aspect ratios.
• /console-tester to boot the port and check the new art and the 16:9 view.