Asset packing
Offline data conversion tool of Jazz² Resurrection.
AssetPacker ("Sources/Utilities/AssetPacker") is a standalone command-line tool that converts the original Jazz Jackrabbit 2 data into the layout a given platform loads. The game does the same conversion on its first run (GameEventHandler::RefreshCache, which forwards to Jazz2::
It also packs and unpacks bitmap fonts (Jazz2::.j2v cinematics into the game's own Jazz2::
Building the tool
- Built by default with the desktop CMake build (
NCINE_BUILD_ASSET_PACKER, defaultON), skipped for cross-compiled targets except the web version below. It links only the base layer and the converters — no renderer, window backend or networking. - After a regular desktop build the binary is
"build/Utilities/AssetPacker/AssetPacker".NCINE_BUILD_GAME=OFFbuilds only the offline tools. - With Emscripten it builds the web version: a WebAssembly module with the repository's
Contentbaked in and a page that swaps the content of a Nintendo 64, Dreamcast, PlayStation 2 or GameCube image in the browser, using the user's own copy of the original game (swap-content --source=, see Replacing the content of a disc image):
emcmake cmake -S . -B build/assetpacker-web -G Ninja -D CMAKE_BUILD_TYPE=Release -D NCINE_BUILD_GAME=OFF cmake --build build/assetpacker-web
The build directory's Utilities/AssetPacker then holds the whole site. Deployment is described in "Sources/Utilities/AssetPacker/Web/README.md". The Emscripten workflow publishes it as the Jazz2_AssetPacker_Web artifact.
Command-line reference
AssetPacker [<command>] [<source>] <target> [options]
Without a command, convert is assumed.
convert [<source directory>] <target directory>— Converts the original game data<source directory>— The original game files (Anims.j2a,*.j2l,*.j2t, ...), or a game installation keeping them in aSourcesubdirectory, in which case itsContentis copied too<target directory>— Output directory, created if needed--source=<dir>— Same as<source directory>(giving both is an error)--content=<dir>— The game's own content (fonts,Animations,Metadata, translations — the repository'sContent). Overrides aContentfound beside the originals, and is needed for a self-contained console or web tree when the two are not kept together--target=<profile>—desktop(default) |console|dreamcast|wii|gamecube|psp|ps2|n64|emscripten(orweb)--n64-tools=<dir>— libdragon's host tools (the toolchain prefix or itsbin) for--target=n64. Defaults to$N64_INST, falls back to the built-in encoders, andbuiltinforces them. See Preparing content for the Nintendo 64--video-downscale=N— Downscale cinematics by N (1–4, 1 keeps the original size). Defaults to 2 forps2and 1 elsewhere. See Cinematics--originals-only— Convert only the episodes and levels the original game shipped--shareware-only— Convert only what the Shareware Demo shipped (implies--originals-only)--all-videos— Deploy every cinematic found, not just the two the game plays--skip-non-episode-levels— Convert only levels that belong to an episode
pack-font <source .png> <target .font>— Packs a grid image and its character list (read from<source .png>.json, or from the binary<source .png>.fontif there is no JSON)unpack-font <source .font> <target .png>— Unpacks a font into a grid image plus<target .png>.json(the one to edit) and the binary<target .png>.fontapply-palette <source .png> <target .png>— Replaces palette indices with their colors, for editingto-indices <source .png> <target .png>— Resolves an edited image back to the nearest palette indicesrecompress-video <source .j2v> <target .j2v> [--video-downscale=N] [--target=<profile>]— Re-encodes one cinematic. N defaults to 1 or to the profile's value, and the profile also decides LZ4 frames (see The .j2v recompression)convert-music <source .j2b> <target .xm>— Translates a Galaxy Music System module into a FastTracker II module (the first half of what--target=n64does to music)swap-content <source image> [<target image>] --content=<dir>— Replaces theContentof a built Dreamcast.cdi, PlayStation 2.iso, GameCube.isoor Nintendo 64.z64, keeping its bootstrap and executable. Without a target the image is rewritten in placeswap-content <source image> [<target image>] --source=<dir> [--content=<dir>] [options]— The same, converting the original files first for the image's console:.z64isn64, a DiscJuggler.cdidreamcast, an image with a GameCube disc headergamecube, anything elseps2, unless--target=says otherwise.--content=and theconvertoptions apply as forconvertcreate-image <executable .dol> <target .iso> --content=<dir> --apploader=<file> [--target=gamecube] [--game-id=<id>] [--title=<name>]— Makes a bootable GameCube disc image (see The GameCube disc image).--game-id=is the six-character game + maker code (defaultGJJEJR),--title=the name in the disc headerverify-formats <directory> [--sweep-truncated]— Reads every level and tile set in the game's own format under the directory (recursively) and writes it back into memory, which has to give the same file byte for byte, or, for a file written by another tool, the same content once read back. Original JJ2 files are skipped.--sweep-truncatedalso reads every file cut short. It checks Jazz2::Formats:: LevelReader, Jazz2:: Formats:: LevelWriter and Jazz2:: Formats:: TileSetFile against real data, which the editors rely on when they save a file they opened (Jazz2:: AssetPacker:: FormatVerifier). See Checking the level and tile set formats level-to-text <source .j2l> <target .txt>— Writes a level of the game's own format as text, one thing on a line, so versions of it can be compared and merged by the usual tools. The text is checked to give the same level again before it's written. See Levels as texttext-to-level <source .txt> <target .j2l>— Makes the level of such a text again, the same file byte for byte as the level it came fromfuzz-formats <directory> [<findings directory>] [--iterations=N] [--seed=N] [--timeout=seconds] [--memory-limit=MB] [--focus-level-texts]— Attacks the readers with seeded random mutations of the levels and tile sets in the game's own format under the directory. See Fuzzing the readers
Progress and warnings go to stdout, errors to stderr. The exit code is non-zero on failure.
Converting the game data
A conversion has two inputs: the original game files and the game's own Content. A game installation keeps both together (originals in Source, beside Content and Cache). When the source is an installation and the target is not desktop, its Content is copied as well. From a repository checkout, name them separately:
AssetPacker ./build/ConsoleContent --source=<original Jazz Jackrabbit 2> --content=./Content --target=console
Anims.j2a(or the sharewareAnimsSw.j2a) is required. Sprites and sounds go into a package (Source.pakfordesktop,Prebaked.pakotherwise). Levels, tilesets, episodes and music follow via Jazz2::Compatibility:: AssetConverter. Plus.j2dof a JJ2+ installation, if it's beside the levels, gives a level made for JJ2+ the textures its textured layers name (TEXTURE::Texture), stored in the converted level. Without it, such a layer gets a texture made up of smooth noise in the same colors, so a reflection still ripples.--source=and the positional source resolve the same way. With--source=a lone positional argument is the target.--content=wins over aContentfound beside the originals.
Target profiles
| Profile | Output |
|---|---|
desktop | A Cache subdirectory plus the Source.idx index the game checks on startup (see Pitfalls). No music (the game reads its Content/Music) and no cinematics (read from the originals) |
console, dreamcast, wii, gamecube, psp, ps2 | A staged Content tree written directly into the target, with Prebaked.pak and no index. The target name only decides the cinematics and LZ4 images |
emscripten | The same kind of prepared tree for the web build |
n64 | A console tree with sound, music and cinematics in libdragon's formats, see Preparing content for the Nintendo 64 |
Non-desktop trees:
- The name
Prebaked.pakmarks the tree as converted, so consoles that can convert (PSP, Wii, PlayStation 3) skip the conversion — see Jazz2::ContentResolver:: IsContentPrebaked(). No index is written because a prepared tree is never rewritten. - Converted levels carry their own version (Jazz2::
Formats:: LevelFile) and the game reads only its own, so a tree from an older tool must be converted again — see the warning in Preparing the game content. - The game's own
AnimationsandMetadatago insidePrebaked.pak, while translations, levels, tilesets, music and cinematics stay loose files. Converted files are written first, so on a path present in both, the asset from the original data wins. - A hand-made multi-frame sprite sheet in
Content/Animationswider or taller than 512 pixels is re-laid out (Jazz2::AssetPacker:: SpriteRepacker): frames are trimmed and packed so none crosses the PSP's 512-pixel texture page line. Smaller grids are copied as they are, since some are sampled as a whole texture. .pofiles are left out, because the game loads only.mo.- For
n64,dreamcast,ps2andgamecube, whose builds have no level editor, theEditordirectory (what only the editor reads, such as its font) is left out, and so are the texts of theeditorcontext in the translations. - Both rules are Jazz2::
AssetPacker:: ContentFilter, which swap-contentandcreate-imageput a tree on an image by as well.
Level filters
--originals-onlykeeps the original episodes plus every level reachable from them.--shareware-onlynarrows that to the Shareware Demo.--skip-non-episode-levelsdrops levels that belong to no episode.- Skipped levels are listed by name — the list of original levels is maintained by hand, so check it for levels that should have been kept.
- Music: a track is kept if a surviving level uses it, plus
menu,bonus2,bonus3(main menu),introandending(cinematics), which no.j2lnames.
Cinematics
The game plays only Intro and Ending. Logo is deployed only with --all-videos. Files go to a Cinematics subdirectory under lowercase names.
| Target | Cinematics |
|---|---|
desktop | Nothing — the game reads the originals in place |
dreamcast, gamecube, ps2, or any profile with --video-downscale above 1 | Re-encoded into Jazz2:: |
| Everything else | Copied unchanged |
Inflating the original format is too slow on the Dreamcast and PlayStation 2, and on the GameCube its four interleaved streams make disc reads too slow, while the re-encoded file is read sequentially. The Dreamcast and GameCube keep 640×480, but the PS2 defaults to --video-downscale=2 (320×240, drawn smoothly upscaled) to keep disc reads small. The player picks its runtime downscale from the actual frame width, so a pre-downscaled file is not halved again.
The .j2v recompression
The original .j2v (CineFeed signature) is 640×480 in four interleaved zlib streams. Jazz2::
- At the original size frames are taken over exactly, indices and palettes alike.
- Downscaled, each pixel is the area average in linear light, and every stretch of frames sharing one original palette gets a new palette (median cut refined by k-means).
The container: the game's usual signature/type/version fields, then width, height, frame delay, frame count, pixel format, codec and an extension area older players skip, then one size-prefixed payload per frame. A frame is a flag byte (bit 0 — a 256-entry BGRA palette follows) and commands up to an end-of-frame marker:
- literal — bytes stored as they are
- run — one repeated byte
- skip — keep the previous frame's pixels
Each command has a single-byte short form and a long form with a 16-bit count. Opcode ranges are on Jazz2::memcpy and memset over a reused frame buffer.
- The re-encoded file is substantially larger than the zlib original, so re-encode only where the platform needs it (the per-target defaults already do). Use
recompress-videoto experiment. dreamcast,gamecubeandps2also compress every frame payload as an LZ4HC block (codec Jazz2::VideoFormat:: CodecDeltaRleLz4), because the plain stream exceeds what their drives deliver. A player without LZ4 refuses such a file, so swap-contentwrites LZ4 frames only onto a disc whose cinematics already have them (see Replacing the content of a disc image).
Font packing
A font is authored as a grid image (one equal cell per character) plus a description of the cell size, character set and advances. The game loads a single .font file (version 2, Jazz2::
The description exists as <image>.png.json (the one to edit) and the binary <image>.png.font (same fields, non-ASCII characters in UTF-8). unpack-font writes both. pack-font uses the JSON if present, otherwise the binary, and prints which one it used.
pack-font does:
- Trimming — Each glyph is reduced to its inked bounding box. The rest of the cell becomes its bearing, so it draws exactly where the cell did. A glyph with no inked pixels (a space) has zero size.
- Index normalization — Every pixel is either a palette index or index 0 (nothing). Ambiguous pixels (transparent in one channel only, partially covered) are resolved, with a warning giving the count.
- Packing — As for converted sprite sheets (Jazz2::
Compatibility:: JJ2Anims:: PackRectangles()), with a FontFormat::GlyphMargin(1 px) margin around each glyph. The chosen atlas minimizes the power-of-two-padded area, then stays within one 512×512 page if possible, then minimizes the exact area. It is stored at its exact size. No glyph crosses a multiple of 512 on either axis (PSP texture pages). - Encoding — After the identifying bytes (signature, file type, version, flags, compressed size), one deflate block holds the atlas size, line height, base spacing, character counts, a 9-byte glyph record per character (position, size, bearings, advance, plus a 32-bit codepoint for non-ASCII), and the atlas as palette indices in the QOI-based image encoding.
Limits (exceeding any is an error):
| Item | Maximum |
|---|---|
| Atlas | 1024×1024 |
| Glyph size | 255 px in either direction |
| Bearing | 127 |
| Characters in the ASCII range | 255 |
| Characters outside it | 65535 |
unpack-font places glyphs back into cells at their bearings, so repacking gives the same font. The unpacked atlas holds palette indices (it looks like near-black noise): run apply-palette before editing and to-indices after, which warns when a color has no exact match. PNG images are read and written by nCine::WITH_PNG_ENCODER for its encoder, which the game without the level editor leaves out.
The JSON description
{ "CellWidth": 15, "CellHeight": 20, "Columns": 19, "LineHeight": 20, "BaseSpacing": -2, "AsciiFirst": 32, "AsciiCount": 95, "Characters": [ { "Char": " ", "Advance": 5 }, { "Char": "!", "Advance": 4 }, { "Char": "\"", "Advance": 6 }, { "Char": "é", "Advance": 8 }, { "Codepoint": 120071, "Advance": 11 }, { "Fallback": true, "Advance": 8 } ] }
| Field | Meaning |
|---|---|
CellWidth, CellHeight, Columns | Required. Cell size (up to 65535) and cells per row (up to 255) |
LineHeight | Distance between lines, defaults to the cell height |
BaseSpacing | Pixels added between characters, negative to tighten (signed 16-bit), default 0 |
AsciiFirst, AsciiCount | The contiguous directly-indexed run, derived from the leading run of consecutive characters if omitted. The first AsciiCount entries must be exactly that run, it must end by U+00FF, and the game keeps only the part below U+0080 |
Characters | Required, at least one entry, in the order of the cells in the image. Char gives the character, Codepoint a number, Fallback marks the single glyph drawn for missing characters (same as "Codepoint": 0). Advance (required, up to 255) is the pen movement. Size and bearings are measured from the image |
A field out of range, missing or of the wrong type is an error naming it (and the list position), as is a list not starting with its claimed ASCII range — which also catches a duplicate inside it:
Error: "font_small.png.json" has to list the ASCII range first, one character after another from U+0020, but the character at position 34 is U+0041 where U+0042 was expected
A codepoint listed twice outside the range, or a character below U+0080 left out of it, is only a warning, but the game never draws that glyph:
Warning: "font_small.png.json" lists U+0104 more than onceComments, trailing commas and a byte order mark are tolerated, but the tool writes UTF-8 without a BOM.
Preparing content for the Nintendo 64
--target=n64 converts sound, music and cinematics into libdragon's formats, so the console can play music and everything fits a 64 MB cartridge. If libdragon's host tools are available it runs audioconv64, and videoconv64 with ffmpeg and ffprobe on the PATH:
AssetPacker convert ./build/ConsoleContentN64 --source=<original Jazz Jackrabbit 2> --content=./Content \ --target=n64 --n64-tools=<libdragon toolchain prefix>
Otherwise (or with --n64-tools=builtin) it uses built-in encoders, the only option in the web version: libdragon's own codecs vendored in Sources/Dependencies (VADPCM, ULC, libxm, driven by Wav64Writer and Xm64Converter) and its own Mpeg1Encoder. The output plays the same — sound effects and pre-rendered music are byte-identical to audioconv64's. The built-in encoders compile only with GCC, Clang and Emscripten, so an MSVC build of the tool needs libdragon's tools for this profile.
Differences from a console tree:
- Sound effects — written beside the package as one VADPCM
.wav64each (Animations/<path>.wav64), streamed from the cartridge. VADPCM is used rather than raw PCM, which costs the mixer more per frame. The originals are not kept: a sound without its.wav64is silent. - Music —
.j2bmodules are translated to FastTracker II modules (asconvert-music) and then to.xm64. Other formats are pre-rendered through libopenmpt into a looping.wav64, which needs a packer built with libopenmpt. - Cinematics — MPEG-1 video (
<name>.m1v, 320×240, 24 fps) with a.wav64soundtrack mixing music and sound effects. Withoutvideoconv64or ffmpeg they are re-encoded theconsoleway at half size. - Sprite sheets and tilesets are written in LZ4 (see LZ4 sprite sheets and tilesets). The full game comes to about 38 MB.
LZ4 sprite sheets and tilesets
--target=n64, dreamcast, ps2 and gamecube write every sprite sheet and tileset as LZ4HC blocks of raw pixels. Other targets keep the game's own format. These four builds decode it with NCINE_WITH_LZ4 (on by default for exactly them).
- A tileset gets one block per 32-row band (one row of tiles), the unit the game builds its atlas in.
- A sprite sheet is one block, stored in the package without further compression.
- Hand-made sheets from
Contentare converted too, but fonts and episode images keep the game's format.
Both headers carry JJ2Anims::ImageContentLz4Flag, so a build without LZ4 reports the file instead of drawing garbage — rebuild the tree for that target, or the target with NCINE_WITH_LZ4.
Replacing the content of a disc image
The Dreamcast, PlayStation 2 and GameCube boot from read-only discs whose content is baked in at build time (see Preparing the content tree, Preparing the content tree and The disc image). swap-content opens a finished image (or Nintendo 64 ROM), keeps everything except Content, and writes it back around a new one — no console toolchain needed.
AssetPacker convert ./build/DreamcastContent --source=<original Jazz Jackrabbit 2> --content=./Content --target=dreamcast AssetPacker swap-content ./jazz2.cdi --content=./build/DreamcastContent AssetPacker convert ./build/Ps2Content --source=<original Jazz Jackrabbit 2> --content=./Content --target=ps2 AssetPacker swap-content ./jazz2.iso --content=./build/Ps2Content AssetPacker convert ./build/ConsoleContentN64 --source=<original Jazz Jackrabbit 2> --content=./Content --target=n64 AssetPacker swap-content ./jazz2.z64 --content=./build/ConsoleContentN64 AssetPacker convert ./build/ConsoleContentGameCube --source=<original Jazz Jackrabbit 2> --content=./Content --target=gamecube AssetPacker swap-content ./Jazz2.iso --content=./build/ConsoleContentGameCube
With --source= both steps are one (this is what the web version runs):
AssetPacker swap-content ./jazz2.z64 ./jazz2-new.z64 --source=<original Jazz Jackrabbit 2> --content=./Content
- The
--content=directory becomesContentwhatever its name, so it must be a conversion for that console's target. - With
--source=, LZ4 images (LZ4 sprite sheets and tilesets) and LZ4 cinematic frames (The .j2v recompression) are written only if the content already on the disc has them, since older game builds draw garbage from LZ4 images or refuse LZ4 videos. GameCube discs and Nintendo 64 cartridges always get LZ4 images. - Without a target image the source is rewritten in place via a
.tmpbeside it, which replaces it only once fully written.
What is kept unchanged:
| Image | Kept |
|---|---|
Dreamcast .cdi | IP.BIN (32 KB: bootstrap, licence screen, serial number, title) and 1ST_READ.BIN, still scrambled |
PlayStation 2 .iso | SYSTEM.CNF, the executable it names, the .IRX modules |
GameCube .iso | Disc header and apploader (first 32 KB) and Jazz2.dol — which moves, and the header's pointer to it is updated |
Nintendo 64 .z64 | Header (save type, accessories), bootcode, executable and its symbol table |
What convert leaves out for these consoles is never put on an image either (Jazz2::AssetPacker::ContentFilter: .po files and the Editor directory, none of them has the level editor).
On a Nintendo 64 ROM the content is the DragonFS image at the end, found via the table of contents n64tool writes after the bootcode. It is rebuilt like mkdfs does (the same tree gives an identical ROM except the table's cookie) and staged like the build does (cmake/n64_stage_content.cmake: original music formats and cinematics that have a video are left out, Source.pak becomes Prebaked.pak). A ROM that would exceed 64 MB is refused.
What it actually does
The file system is generated from scratch (Jazz2::.cdi that is the first session's audio track, the pregap, the track layout and the trailing descriptor. A plain .iso is just the data track of 2048-byte sectors. The type is read from the file's last eight bytes.
The volume matches what mkdcdisc writes:
- Two hierarchies — plain ISO 9660 (where the Dreamcast bootstrap finds
1ST_READ.BIN, with upper-case restricted names) plus Joliet with the real names, which KallistiOS uses whenever present (fs_iso9660.c). - Files at the outer edge — file data is placed at the end of the volume for faster reads (
mkdcdisc's default,-Nturns it off), which is why the image is far larger than its content. - Mode 2 Form 1 sectors for a
.cdi(2336 bytes stored per sector), with the error detection code and both Reed-Solomon parities generated — wrong parity means read errors. A plain.isostores 2048 bytes per sector and needs none of it.
A .cdi keeps its length when the new content fits. Otherwise the track grows and the descriptor's three length fields and the disc length are adjusted. A disc exceeding an 80-minute CD is still written, with a warning. A plain .iso is always sized to its content.
The GameCube disc image
create-image writes the GameCube disc image. The GameCube build runs it when given a host build of the tool (GAMECUBE_ASSETPACKER_EXECUTABLE, see The disc image). It is an ordinary ISO 9660 volume (Jazz2::
- the disc header (
boot.bin): game ID, GameCube magic word, title and executable offset, bi2.bin: the assumed memory size and the region, which the boot ROM checks,- the apploader, which loads the executable. Nintendo's cannot be redistributed and devkitPro ships none, so the GameCube target builds a minimal one from
"Sources/nCine/Backends/Ogc/GameCubeApploader.c".
The executable and Content are ordinary files with Joliet names. The game reads them through ISO 9660 (see OgcDvd.h). The volume is followed by 32 KB of zeros, because a read past the image end is an error in Dolphin. There is no GameCube file system table, so tools that list a disc by it show no files.
Checking the level and tile set formats
Levels and tile sets in the game's own format (Jazz2::
Verifying files
verify-formats <directory> [--sweep-truncated] goes through every native level and tile set under the directory:
- Each is read whole and written back into memory: byte for byte the same file, or, for a file written by another tool, the same content once read back again.
- With
--sweep-truncated, each is also read cut short at many places — at every byte of its first 32, at 40 places spread over the rest, and at each of its last 4 bytes. A cut level must never be read as anything but the whole level (a cut that takes only the end of the compressed body can leave all of it readable), a tile set cut before its image content must be refused. That reads every file 76 more times, which makes the whole check many times slower, so it's left for when the readers themselves change. - Levels are checked for what the reader can't check on its own, how the records refer to each other: a default or extra tile set path the game wouldn't look up (Jazz2::
Formats:: LevelFile:: IsSafeTileSetPath()), an embedded tile set that can't be read or has fewer tiles than the level takes, tiles and animation frames beyond the tiles of the level, overridden tiles that aren't of a tile set, and off-grid events far outside of the level. These are warnings — the game copes with them — and don't fail the check.
The exit code is non-zero if a file differs, can't be read, or (with --sweep-truncated) passes for something else when cut.
Levels as text
level-to-text <source .j2l> <target .txt> writes a level as text (Jazz2::text-to-level <source .txt> <target .j2l> makes the level of it again — the same file byte for byte, as Jazz2::level-to-text checks that before it writes the text. Levels kept as text can be compared line by line and merged by the usual tools of version control.
- The text starts with a
formatline, one thing follows on a line, lines starting with#are comments. - Strings are quoted, with C escapes for
",\and the control characters. Floating-point values are written so they're read back exactly, or asbits:XXXXXXXXif they aren't numbers. - A tile is its ID, followed by
:and its flags in hexadecimal if it has any. Only the events of the grid that aren't empty are written, each with its position. - Binary data — the tile sets a level stores in itself, the payload of a chunk — is written as Base64 lines up to
end.
Fuzzing the readers
fuzz-formats <directory> [<findings directory>] attacks the readers with seeded random mutations of the native levels and tile sets under the directory (Jazz2::
An input that crashes, fails an assertion, hangs, asks for too much memory or doesn't survive is saved into the findings directory ("FuzzFindings" by default) as <reason>-<index>-<file>. A crash, a hang or too much memory also ends the run. Given a single file instead of a directory, the command only runs it through the readers once, to reproduce a finding.
| Option | Meaning |
|---|---|
--iterations=N | Number of inputs to try, 10000 by default |
--seed=N | Seed of the mutations, 1 by default. The same seed tries the same inputs again |
--timeout=seconds | How long a single input may take before it counts as a hang, 30 by default |
--memory-limit=MB | Memory the process may use before an input counts as asking for too much, 3072 by default, at least 64 (Windows only) |
--focus-level-texts | Only levels, each given a chunk of translated texts, and that chunk attacked more |
AssetPacker fuzz-formats ./Cache --iterations=100000 --seed=7 AssetPacker fuzz-formats ./FuzzFindings/crash-1234-castle1.j2l
Platform notes
Where each console expects its tree is described in Building for consoles.
| Platform | Profile | Notes |
|---|---|---|
| Desktop | desktop | Optional — the game converts on first run. Useful for build pipelines or pre-downscaling cinematics |
| Dreamcast, GameCube | dreamcast, gamecube | Required (no conversion compiled in). Re-encoded cinematics, LZ4 images. Baked into a disc image, see Preparing the content tree and The disc image. Replace later with Replacing the content of a disc image |
| PSP, Wii | psp, wii | Could convert an installation in Source, but slowly, so a prepared tree is used. Original cinematics copied |
| PlayStation 2 | ps2 | Required. Cinematics re-encoded at 320×240, LZ4 images. A console tree plays, but slower. Baked into an ISO (Preparing the content tree), or run from an SD card in an MX4SIO adapter (Running from a USB stick or an MX4SIO SD adapter) |
| Nintendo 64 | n64 | See Preparing content for the Nintendo 64. A console tree boots without music. Baked into the ROM (Preparing the content tree) |
| PlayStation 3 | console | Could convert, but slowly |
| PS Vita, Switch, Wii U | none | Convert on first run. The tool only skips the wait |
| Web | emscripten | Typically with --shareware-only for the public demo |
Packed .font files are loaded on all platforms, but consoles gain the most (one index per pixel and less power-of-two padding).
Pitfalls
Source.idxmust match the game exactly. It is compared field for field with whatGameEventHandler::WriteCacheDescriptorwrites (signature, file type, cache version, flags,Anims.j2amodification time, event count, build version). Any mismatch makes the game silently reconvert everything. Use a tool built from the same sources as the game.- Never add an index to a console or web tree, and never rename
Prebaked.pak— the game would look for original files it does not have and show a menu with nothing to play. - Missing
Anims.j2a(orAnimsSw.j2a) at the top of the source or in itsSourcesubdirectory makes the tool refuse to run. - A non-desktop tree needs the game's own content — a
Contentbeside the originals or--content=. Without it the conversion still succeeds but the game cannot draw its menu (no fonts,Metadata, UI graphics or translations). The tool warns. A run that got it printsCopying "…". swap-contentreads only what the game's builds produce: a plain.iso, a DiscJuggler.cdiwith 2048 or 2336 bytes per sector (mkdcdisc), and a.z64ending with its DragonFS image. A 2352-byte-sector.cdiis refused, a byte-swapped.v64/.n64must be converted to.z64first, and other containers (.mds,.nrg,.gdi) are not supported..xm64memory sizes are always the 64-bit ones. libxm computes them withsizeofof pointer-holding structures. A 32-bit build (the web version is one) would declare too little and the player refuses the module.Xm64Converteralways declares the 64-bit sizes.- Run one
audioconv64per module. Over several XM files in one run it writes later modules with the first one's offsets, which hangs or crashes the console. The packer does this. Do the same by hand. - Identical samples keep only the first instrument's seek points in an
.xm64. Another instrument sharing the data and played from a different9xxoffset asserts on the console ("invalid VADPCM seeking point"), so the packer makes such copies differ inaudibly (ModuleConverter.cpp).