Building the project for consoles

Guide how to build, deploy and run Jazz² Resurrection on game consoles.

The game runs on eleven consoles. Each is cross-compiled with its own SDK, most use a bespoke window/input backend instead of SDL2 or GLFW, and seven have no programmable shaders, so they use one of six fixed-function rendering backends (the Wii and the GameCube share one). This page covers installing the toolchain, configuring, packaging, deploying and getting a log out for each of them. For everything else see Building the project.

ConsoleToolchain (CMake toolchain file)Rendering backendWindow backendBuild artifact
Nintendo 64libdragon (cmake/toolchains/n64.cmake)RDP — fixed-functionN64jazz2.z64 (bootable ROM)
Sega DreamcastKallistiOS (kallistios.toolchain.cmake)PVR — fixed-functionDcjazz2.cdi (bootable disc image)
Nintendo WiidevkitPPC + libogc (Wii.cmake)GX — fixed-functionOgcboot.dol (in a staged sd/ tree)
Nintendo Wii UdevkitPPC + wut (WiiU.cmake)GX2 (native, shaders)SDL2jazz2.wuhb (Wii U Homebrew Bundle)
Nintendo GameCubedevkitPPC + libogc (GameCube.cmake)GX — fixed-functionOgcjazz2.iso (bootable disc image) and Jazz2.dol (in a staged sd/ tree)
Nintendo 3DSdevkitARM + libctru + citro3d (3DS.cmake)PICA — fixed-functionCtrJazz2.3dsx (in a staged sdmc/ tree)
PlayStation Portablepspdev (pspdev.cmake)GU — fixed-functionPspEBOOT.PBP (in a staged ms0/ tree)
PlayStation 2ps2dev (ps2dev.cmake)GS — fixed-functionPs2jazz2.iso (bootable disc image)
PlayStation 3ps3toolchain + PSL1GHT (cmake/toolchains/ps3dev.cmake)RSX (native libgcm, shaders)Ps3jazz2.pkg (and an unsigned jazz2.self)
PlayStation VitaVitaSDK (vita.toolchain.cmake)GXM (native sceGxm, default), OpenGL via vitaGL (ES 2.0 profile) or SoftwareSDL2jazz2.vpk
Nintendo SwitchdevkitA64 (Switch.cmake)OpenGLSDL2jazz2.nro

On the fixed-function ones NCINE_PREFERRED_RHI is pinned to the console's one backend and any other value is a configure error. The PlayStation 3's RSX and the Wii U's GX2 are full shader backends, so they keep the post-processing chain and differ from desktop mainly in when their shaders are compiled (see PlayStation 3 and Nintendo Wii U). The PS Vita and the Switch are ordinary shader platforms. For them mostly the deployment parts apply.

What every console build shares

  • The host tools are not built. ShaderCompiler and AssetPacker are skipped for cross-compiled targets. The generated shader headers are committed to the repository. The game content is prepared ahead of time.
  • The game data is converted in advance with AssetPacker. The Nintendo 64, Dreamcast, PlayStation 2 and GameCube have no first-run conversion compiled in (NCINE_HAS_WRITABLE_CACHE in "Sources/Main.h") and don't verify their content, so a build without a prepared tree reaches the main menu with no episode to play. The Wii, Wii U, 3DS, PSP, PS3, Vita and Switch can convert on the device, but skip it when they find a prepared tree.
  • Seven of them have no shaders. RDP, PVR, GX, GU, GS and PICA implement each effect as fixed-function passes transpiled by ShaderCompiler from the same .shader files — see console fixed-function blocks. There is no post-processing chain and no rescale filter. The level viewport is aspect-fitted into the console's native output.

Preparing the game content

All data-prepared consoles consume the same tree, prepared once with AssetPacker and pointed at from each console build. Only the cinematics differ: the Dreamcast and the GameCube need their own profile, and the Nintendo 64 needs its own conversion that also covers sound and music. The dreamcast, ps2, gamecube and n64 profiles also write sprite sheets and tilesets in LZ4 (see LZ4 sprite sheets and tilesets), while the generic console tree keeps the game's own format.

1. Build the tool. It is part of any desktop build (NCINE_BUILD_ASSET_PACKER). Naming the target builds only the tool:

cmake -B ./build/ -D CMAKE_BUILD_TYPE=Release
cmake --build ./build/ --target AssetPacker --parallel $(nproc)

The binary lands at "build/Utilities/AssetPacker/AssetPacker".

2. Convert. Pass the original game data and the repository's "Content" separately:

./build/Utilities/AssetPacker/AssetPacker ./build/ConsoleContent \
    --source=<path to the original Jazz Jackrabbit 2> --content=./Content --target=console

The tree is written straight into the target directory (not into a "Content" subdirectory, created if missing). A full game installation, which has both halves in "Source" and "Content", can be passed as a single positional argument instead ("AssetPacker <installation> ./build/ConsoleContent --target=console"). A bare copy of the original game converted without "--content=" produces a tree with no fonts, "Metadata" or translations that cannot even draw its menu. The tool warns about it.

Pick the profile by the cinematics:

--target=ForCinematics
consoleEvery console except the Dreamcast and the GameCube (wii and psp are aliases)Original .j2v files copied unchanged
dreamcastSega DreamcastRe-encoded into Jazz2::VideoFormat (LZ4 block per frame, since the SH-4 cannot inflate the original in time)
gamecubeNintendo GameCubeRe-encoded the same way (the original's interleaved streams cannot be read from disc fast enough)

Options that make the tree smaller (the rest are in Command-line reference):

  • --originals-only — only the episodes the original game shipped
  • --shareware-only — only the Shareware Demo
  • --skip-non-episode-levels — drop levels that belong to no episode
  • --video-downscale=N — shrink the cinematics by 2 to 4 (re-encodes on any profile)

3. Check the output. A complete tree looks like this:

build/ConsoleContent/Prebaked.pak          # sprites and sounds, plus "Animations" and "Metadata"
build/ConsoleContent/Episodes/…            # the episodes and their levels
build/ConsoleContent/Tilesets/…
build/ConsoleContent/Music/…
build/ConsoleContent/Cinematics/intro.j2v  # and "ending.j2v"
build/ConsoleContent/Translations/…        # the ".mo" files

A tree with "Source.pak" instead of "Prebaked.pak" came from the desktop profile and is wrong for a console.

4. Point the console build at it with NCINE_CONTENT_DIR:

cmake -B ./build/<console>/ … -D NCINE_CONTENT_DIR=$PWD/build/ConsoleContent

The variable is cached: give it on the first configuration of a build directory, or re-run CMake with it on an existing one. Unset, it defaults to the repository's "Content", which boots to a main menu with no episode. Each build stages the directory under the name "Content" at the place the console reads it:

ConsoleContent directoryCache / save data
Nintendo 64"rom:/Content/" (ROM's DragonFS image)"rom:/Cache/", read-only, preferences on the cartridge EEPROM ("eeprom:/JAZZ2CFG")
Dreamcast"/cd/Content/" (disc image)"/cd/Cache/", read-only, preferences and resumable state on a memory card ("/vmu/<port><unit>/Jazz2" and "Jazz2.resume")
Wii"sd:/apps/Jazz2/Content/""sd:/apps/Jazz2/Cache/"
Wii U"fs:/vol/content/" (inside the .wuhb)"sd:/wiiu/apps/Jazz2/Cache/" ("fs:/vol/external01/…")
GameCube"dvd:/Content/" (disc image), or "Jazz2/Content/" on an SD card (sd:, carda: or cardb:, see The disc image)Disc: read-only, preferences and resumable state on a memory card ("mca:/Jazz2.config" and "Jazz2.resume"). SD card: "Jazz2/Cache/", writable
Nintendo 3DS"sdmc:/3ds/Jazz2/Content/""sdmc:/3ds/Jazz2/Cache/"
PlayStation Portable"ms0:/PSP/GAME/Jazz2/Content/""ms0:/PSP/GAME/Jazz2/Cache/"
PlayStation 2"cdfs:/Content/" (disc image)"cdfs:/Cache/", read-only, nothing staged
PlayStation 3"/app_home/Content/" (next to EBOOT.BIN)"/dev_hdd0/game/JAZZ20000/USRDIR/Cache/", writable
PlayStation Vita"app0:/Content/" (inside the VPK)"ux0:/data/jazz2/Cache/"
Switch"romfs:/" (embedded in the .nro)"sdmc:/Games/Jazz2/Cache/"

On the PlayStation 3 "/app_home" maps to the running executable's directory (USRDIR), so the same build runs installed and straight from the staged package directory, which is how RPCS3 boots it. The Source, configuration and log locations of every platform are in File locations.

"Prebaked.pak" marks a tree as prepared: a platform that could convert (Wii, Wii U, 3DS, PSP, PS3, Vita, Switch) then skips the conversion, leaves Cache alone and never looks for the original game files. To convert on the device instead, leave the prepared tree out and put an original installation into the console's Source directory.

The Nintendo 64 packs the tree into the ROM's DragonFS image, the Dreamcast and the PlayStation 2 into a disc image. For these three:

  • The medium is all the game will ever have. No conversion, no writable Cache and no content check — an incomplete tree just shows a main menu with nothing to play.
  • The staging directory is added to, not replaced. NCINE_CONTENT_DIR is copied into its Content subdirectory on every build, so files removed from the tree survive and get packed into later images. The N64 build clears it first. For the Dreamcast and PS2 delete "<build dir>/cd/" by hand after regenerating a tree.

What is available on which console

Decided at configure time from the platform. Values are for a default Release configuration.

FeatureN64DreamcastWiiGameCubeWii U3DSPSPPS2PS3VitaSwitch
Threads (NCINE_WITH_THREADS)NoYesYesYesYes (newlib pthreads)Yes (pthread shim over libctru)YesNoNoYesYes
Asynchronous tracing (DEATH_TRACE_ASYNC)NoNoNoNoNoNoNoNoNoNoNo
Audio backendN64 (RSP mixer)AICAASNDASNDSDL (software mixer, AX voices through wiiu-sdl2)NDSPPSPPS2PS3OpenAL if the SDK has oneOpenAL if the SDK has one
Sound effectsYesYesYesYesYesYes (needs DSP firmware, see Limits and known issues)YesYesYesSDK-dependentSDK-dependent
Module musicYes (XM64, converted ahead, see Limits and known issues)Yes (libxmp, see Limits and known issues)Yes (libxmp, see Limits and known issues)Yes (libxmp, see Limits and known issues)Yes (libxmp)Yes (libxmp)Yes (libxmp, see Limits and known issues)Yes (libxmp, see Limits and known issues)Yes (libopenmpt, from source, single-threaded)Yes (libopenmpt, with libxmp packaged too, see Limits and known issues)SDK-dependent
Underwater low-pass filterNoNoNoNoNoNoNoNoNoSDK-dependentYes
Local splitscreenNo — needs threadsYesYesYesYesYes (one controller)Yes (one controller)No — needs threadsNo — needs threadsYesYes
Online multiplayerNoNoNoNoNo (not enabled yet, see Limits and known issues)Yes (ENet only, see Limits and known issues)Yes (ENet only, see Limits and known issues)NoNoYes (ENet only, see Limits and known issues)Yes
Post-processing and rescale filtersNoNoNoNoYesNoNoNoYesYesYes
X-ray and blur-behind tile layers (TILEMAP_LAYER_EFFECTS)No — reduced at loadNo — reduced at loadNo — reduced at loadNo — reduced at loadYesNo — reduced at loadNo — reduced at loadNo — reduced at loadYes (microcode generated, not yet run on a console)YesYes
External .shader filesNoNoNoNoNo (shaders are compiled offline)NoNoNoNo (no runtime compiler)YesYes
Converts the game data itselfNoNoYesNoYesYesYesNoYesYesYes

Audio backends

WITH_AUDIO compiles the audio subsystem in, with exactly one audio backend chosen at configure time from the platform. A backend implements nCine::IAudioDevice. nCine::AudioBuffer, nCine::IAudioPlayer and nCine::AudioStream contain no backend calls, so a console only has to provide a device. Backends live in "nCine/Audio/Backends/<backend>/".

BackendWITH_*What it drives
ALWITH_OPENALSystem OpenAL on desktop, the SDK's own on the Switch and Vita
ASNDWITH_ASNDlibogc's DSP mixer (Wii and GameCube, ships with devkitPPC)
AICAWITH_AICAThe Dreamcast sound processor through KallistiOS: wavetable channels for effects, snd_stream for music
PS3WITH_PS3AUDIOPSL1GHT's libaudio (lv2 offers only an output ring, so this backend is a software mixer on the PPE)
PSPWITH_PSPAUDIOInteger software mixer into one sceAudio channel, on its own thread
NDSPWITH_NDSPSame mixer into one libctru NDSP channel on a higher-priority thread. The DSP resamples, so any mixing rate is valid. Needs the DSP firmware, see Limits and known issues
N64WITH_N64AUDIOlibdragon's RSP mixer into the AI ring. Effects stream from .wav64 files the asset packer writes, music is libdragon's .xm64 player, cinematic soundtracks play through libdragon's video player (NCINE_HAS_NATIVE_AUDIO)
PS2WITH_PS2AUDIOSoftware mixer into the audsrv IRX stream, topped up per frame (no threads). The SPU2 resamples in hardware
SDLWITH_SDLAUDIOSoftware mixer into SDL2's audio stream. On the Wii U, wiiu-sdl2 plays it through AX voices (devkitPro ships no OpenAL there)
none—Silent fallback when no backend is available or audio is turned off

Each console's SDK provides what its backend needs, so nothing has to be installed by hand. NCINE_WITH_AUDIO is ON everywhere. Clearing it removes the whole subsystem.

Backends that mix on the main thread starve when it blocks longer than they have queued, e.g. during a level load. nCine::IAudioDevice::BeginBlockingOperation() and its counterpart are called around the level load and the episode scan, and the PS2 stops its stream for the duration (see Limits and known issues).

Getting a log out of a console

Every console writes the same trace output as desktop, but each needs a different receiver. Set it up before debugging anything.

ConsoleWhere the trace goes
Nintendo 64stderr via libdragon's debug sinks: the ISViewer window (ares prints it to its terminal) and the USB log of an EverDrive/SC64, both probed at startup. The boot console shows startup messages until the renderer takes over
Dreamcastdbgio: the framebuffer console during startup, then the SCIF serial port. Emulators print it to their log, dc-tool to its console
Wii / GameCubeA USB Gecko on EXI channel 1 (memory-card slot B), probed at startup. Without one nothing is written. Dolphin serves it on TCP port 55020 (or the next free one) with slot B set to "USB Gecko". Jazz2.log is written beside the content on an SD card, never to a GameCube memory card
Wii UOSReport(): Cemu shows it with coreinit logging on, on a console any logging module of the Aroma environment that listens to it. Jazz2.log is written to "sd:/wiiu/apps/Jazz2/" too
Nintendo 3DSsvcOutputDebugString: Azahar logs it under Debug.Emulated (hidden by its default filter, see Deploying and running), or an attached debugger. The bottom-screen console shows every line until the renderer starts, then warnings and errors. Jazz2.log is written next to the .3dsx
PlayStation Portablestdout via sceIoWrite on fd 1: PPSSPP log, psplink console, plus the debug screen until the GU takes over
PlayStation 2The EE SIO transmit register (0x1000F180): PCSX2 shows it as EE console output with EnableEEConsole on, a serial cable on hardware. Plus the boot console (libdebug) until the renderer starts — after the disc wait, IOP module loads and content/memory-card probes — so a stalled boot leaves its last line on screen
PlayStation 3sysTtyWrite: fd 1 and 2 go to the console TTY on hardware and to RPCS3's log
PlayStation VitasceClibPrintf, read with host tools (psp2shell, VitaCompanion)
SwitchsvcOutputDebugString, read with a host debug logger. A log file on the SD card is always written too

DEATH_TRACE_LOG_PATH forces the trace into a file on platforms with writable storage (not the Dreamcast). Verbose I/O lines are deferred and flushed only when an error follows, so a sparse log is normal. Where Jazz2.log ends up on each console is listed in Consoles.

The log header names the device via nCine::Application::GetDeviceHostname() — the console nickname (Wii, 3DS, Switch), WLAN MAC (PSP), OpenPSID (Vita, PS3), i.Link ID (PS2) or BIOS system ID (Dreamcast). It is empty on the GameCube and N64.

Tile layers are indexed meshes

A tile layer is drawn as one mesh (TILEMAP_USE_SINGLE_DRAW, on everywhere except the software renderer), as are destructible debris and, with shaders, the lighting quads. The mesh is indexed: four vertices per quad plus six indices from a shared pattern (RenderResources::GetQuadIndices() — 0, 1, 2, 0, 2, 3 per quad, relative to the draw's first vertex, allocated once so a render queue may keep the pointer).

  • Shader backends (GL, GXM, RSX, D3D11, Vulkan) draw through the index buffer with base-vertex addressing. OpenGL|ES below 3.2 has no glDrawElementsBaseVertex() and folds the base into the vertex format's offset (RenderCommand::Issue()).
  • Fixed-function backends (GU, GX, PVR, GS, RDP, PICA, LegacyGL) resolve the indices on the CPU via ResolveHostIndices() and a vertexAt() resolver, and quad recognition (one GE rectangle, GX_QUADS quad or GS sprite per tile) still works.

RenderResources::GetMaxQuadsPerDraw() alone decides the chunk length, from the streaming buffer sizes and the 16-bit index range (sceGxm rejects indices above 63999). Larger meshes are split on whole quads.

What a level's grids cost

A level's tile layers and event grid are the largest allocations of a level load — dense, they would be over 3 MB for a large level (768x64 tiles, up to eight layers). Two storage choices reduce that, transparently to readers:

  • The event grid is sparse on every platform: a uint16_t slot per cell into a dense array of only the cells that have an event (EventMap EventLayout). Empty cells read as a shared empty tile. Writes go through Edit(), which allocates the cell, while Find() looks up without allocating. A reference from Edit() is valid only until the next Edit().
  • Draw-only layers store 4 bytes a tile instead of 12 (LayerLayout::CompactDrawOnlyLayers: N64, PSP, Dreamcast, 3DS, PS2). Layout[i] decodes into a small ring of scratch LayerTile values, so a reference survives only the next few lookups. Writes go through Set(). Other platforms keep plain arrays.

Both grids are allocated in blocks of 4096 tiles and without throwing: a level whose grids don't fit fails to load with the main menu's "Cannot load specified level!" instead of aborting.

Work the fixed-function consoles leave out

Shared optimizations on the CPU-transforming consoles. None changes the output visibly or audibly.

  • A fully lit level draws no lightmap. Backends that clamp the lightmap to darkening only declare RHI_LIGHTING_DARKEN_ONLY ("nCine/Graphics/RHI/RhiFwd.h" — PVR, GU, GS, GX, PICA, RDP), and CombineRenderer::PrepareSoftwareLighting() then skips the lightmap entirely at full ambient level.
  • A tile layer's visible window is cached between frames with TILEMAP_CACHE_LAYER_WINDOW ("Jazz2/Tiles/TileMap.h") and re-issued under a new translation until it moves by a whole tile or a tile changes. Animated tiles stay per-frame. It needs a backend whose tile-mesh dispatch applies the model matrix — every shader backend plus GX, PICA, GS and GU. The N64 has its own cache in the RDP tile format. PVR and legacy GL walk every frame. Compact layers (see What a level's grids cost) carry a version stamp bumped on every write for this check.
  • Slow libm calls are replaced. libxmp's per-tick double pow()/log()/divisions and the fixed-function effects' floorf()/ceilf() are soft-float on these CPUs, so "nCine/Base/LibmOverrides.cpp" takes them over through the linker's --wrap:
ConsoleReplacedWhy
Dreamcastpow, log, ceilfThe SH-4 ABI defaults to single precision, so every double operation switches FPU mode
Nintendo 64floorf, ceilfThe VR4300 has no rounding instruction
PlayStation 2pow, log, double division, floorf, ceilfSingle-precision FPU only, and music decodes on the main thread
PSPpow, log, double division, floorf, ceilfSingle-precision FPU only

pow() and log() are computed in single precision within a few ULPs. Whole exponents go to newlib exactly (libxmp's Vorbis decoder needs exact integral powers). Division and rounding are bit-exact. A new target opts in by adding the file to its source list and the --wrap options to its link, both in its arm of "cmake/ncine_extra_sources.cmake".


Nintendo 64

A 93 MHz VR4300 with 8 MB of RDRAM shared by CPU and graphics, and an RDP rasterizer whose only texture memory is a 4 KB TMEM. The Expansion Pak is required — the base 4 MB cannot hold the game. Renders through the RDP backend ("Sources/nCine/Graphics/RHI/RDP") on libdragon (rdpq), presented by the N64 window backend in 320x240 RGB565.

Toolchain

libdragon ships a prebuilt mips64-elf GCC, so only the library is built. Requirements the toolchain file checks:

  • libdragon must come from the preview branch, and must not be built with NDEBUG (the log channels need symbols that build strips).
  • Pin a revision for reproducible builds (CI uses the one in ".github/workflows/n64.yml"). It must be at least 7c57c409 ("rspq: make lowpri buffer handoff atomic") — older revisions stop video with "rspq_next_buffer: wait loop timed out".
# Prebuilt cross-compiler (also available as .deb; extract anywhere, point N64_INST at it)
curl -LO https://github.com/DragonMinded/libdragon/releases/download/toolchain-continuous-prerelease/gcc-toolchain-mips64-x86_64.rpm
rpm2cpio gcc-toolchain-mips64-x86_64.rpm | cpio -idm
export N64_INST=$PWD/opt/libdragon
export PATH="$N64_INST/bin:$PATH"

# Library and host tools, from the preview branch
git clone -b preview https://github.com/DragonMinded/libdragon.git
make -C libdragon -j $(nproc) libdragon && make -C libdragon install
make -C libdragon -j $(nproc) tools && make -C libdragon tools-install

# zlib (required for compressed content, not packaged)
curl -L https://github.com/madler/zlib/releases/download/v1.3.1/zlib-1.3.1.tar.gz | tar xz
cd zlib-1.3.1
for f in adler32 compress crc32 deflate infback inffast inflate inftrees trees uncompr zutil; do
    mips64-elf-gcc -march=vr4300 -mtune=vr4300 -mabi=o64 -O2 -c $f.c; done
mips64-elf-gcc-ar rcs libz.a *.o
cp libz.a "$N64_INST/mips64-elf/lib/" && cp zlib.h zconf.h "$N64_INST/mips64-elf/include/"

Preparing the content tree

This console gets its own conversion, --target=n64, which converts sound effects, music and cinematics into libdragon's formats with libdragon's host tools — that is what gives it music and makes the game fit on a cartridge (see Preparing content for the Nintendo 64). Everything else in Preparing the game content applies.

./build/Utilities/AssetPacker/AssetPacker ./build/ConsoleContentN64 \
    --source=<path to the original Jazz Jackrabbit 2> --content=./Content \
    --target=n64 --n64-tools=$N64_INST
  • audioconv64 is required. videoconv64 plus ffmpeg and ffprobe encode the cinematics.
  • A packer built with libopenmpt pre-renders the tracks not in the game's own module format and mixes music into the cinematics' soundtracks.
  • Sprite sheets and tilesets are written in LZ4 (NCINE_WITH_LZ4, see LZ4 sprite sheets and tilesets).
  • A plain console tree also works, but has no music, and its cinematics must be re-encoded at half size (recompress-video --video-downscale=2) to play at a watchable rate.

Building

export N64_INST=<toolchain prefix>
cmake -B ./build/n64/ -D CMAKE_BUILD_TYPE=Release \
    -D CMAKE_TOOLCHAIN_FILE=./cmake/toolchains/n64.cmake \
    -D NCINE_CONTENT_DIR=<n64 content tree>
make -j $(nproc) -C ./build/n64/

The toolchain file is the project's own (libdragon has no CMake support) and reproduces the machine flags of libdragon's n64.mk. LTO is force-disabled and Release uses -O2.

The build produces "build/n64/jazz2.elf" and the bootable "build/n64/jazz2.z64". A POST_BUILD step reproduces libdragon's ROM layout:

  • n64sym (symbol table for on-console backtraces), n64elfcompress (stripped, compressed executable) and mkdfs (DragonFS image of the content), concatenated by n64tool.
  • ed64romconfig sets eeprom16k (2 KB EEPROM for preferences) and a Rumble Pak in controller 1. The real-time clock is deliberately not declared — an EverDrive cannot provide it together with EEPROM.
  • Content is staged by "cmake/n64_stage_content.cmake", which drops what the console cannot play (original music formats, the original of a cinematic that has a video).

Deploying and running

  • Emulator — "jazz2.z64" boots in ares or simple64 (both default to an Expansion Pak). ares prints the trace (ISViewer) to its terminal.
  • Real hardware — copy the ROM to an EverDrive-64 or SC64. The save type is read from the header. An Expansion Pak must be installed.
  • New content without the toolchain — AssetPacker swap-content jazz2.z64 --content=<n64 content tree> (see Replacing the content of a disc image).

Limits and known issues

This port is experimental: the CPU is an order of magnitude below the next-slowest console, and a level frame takes about 14–31 ms in ares depending on the level.

Memory and size

  • 8 MB unified RDRAM, about 6.3 MB of it heap. Strictest budgets of any console: no episode backgrounds, half the debris caps, the outgoing level is released before the next loads, and the lightmap is combined at 1/12 of the output resolution (27x20 texels).
  • Fragmentation is what fails first, so nothing large is allocated as one block: level grids come in 4096-tile blocks (sparse/compact forms, see the section above), the tileset atlas is built and uploaded in chunks of at most 256 KB, and direct-colour textures are converted straight into their RDP store. A level that does not fit returns to the menu with a message. All animations are deferred (sheets read on first use). The few that would hitch are read behind the loading screen.
  • The executable (1.9 MB) comes out of the same 8 MB as the heap. To keep it small, the bundled JSON library formats with fputs() and parses with strtod() (string streams pull in ~350 KB of <locale>), the port defines its own std::terminate handler ("nCine/MainApplication.cpp", avoids linking the demangler), and the game target is built without RTTI on every platform, since casts use runtime_cast<T>() (DEATH_USE_RUNTIME_CAST, and turning it off brings RTTI back). The last two also help the Dreamcast and PlayStation 2.
  • The display is double buffered (not triple), and the tileset atlas has no TileSet::TilePadding border (75–84 KB saved). That is valid only because tile layers are drawn 1:1 with point sampling — any platform that scales or bilinearly samples them needs the border.
  • The ROM must fit in 64 MB (flashcart and PI bus limit). The build fails if it does not. A --target=n64 tree is about 39 MB with all music and both cinematics.
  • Preferences live in cartridge EEPROM via eepromfs ("eeprom:/JAZZ2CFG", 2 KB). An emulator or flashcart that ignores the header's save type leaves the game unable to save (warned at startup, not an error).

Hardware quirks

  • FPU exception traps are masked at startup. A non-NDEBUG libdragon enables overflow, divide-by-zero and invalid-operation traps, but the game assumes IEEE behaviour (e.g. FLT_MAX squared), so FCR31 enable bits are cleared, keeping only flush-to-zero.
  • Video filters: the display uses FILTERS_RESAMPLE (no AA, no de-dither) and the RDP writes undithered pixels (SOM_RGBDITHER_NONE). De-dither needs more than 320 px width, and VI_AA_MODE_NONE hits a documented NTSC hardware bug at this width — don't switch.
  • TMEM is per-primitive: 4 KB (2 KB for paletted texels) uploaded before each draw, so frame cost tracks distinct texture windows. Tiles upload one 32x32 tile at a time (same-tile runs coalesced). Sprites larger than a window are drawn as row bands. Windows alternate between TILE0 and TILE1.
    • Unused tile descriptors are given harmless values at startup — a real console powers up with random contents (emulators zero them), which two-cycle draws (colorized text) would sample.
    • Two-cycle draws skip alpha compare on screen (the hardware is a pixel off) and keep it only in render targets.
    • A tile's TMEM window must be derived from the same fixed-point texel coordinates as its rectangle. From floats, non-power-of-two atlases overflow the 1 KB slot.
  • Additive blending is drawn as alpha-over: the RDP's additive mode wraps past white to black. Effects that need true summing accumulate on the CPU and are unaffected.
  • A hung RDP reports itself on screen. A watchdog on the VI interrupt detects the RDP stuck on one command for 100 ms, shows its registers, the last state commands and the command words around the stop, and halts. Photograph it — emulators do not reproduce these hangs, and a flashcart without USB cannot deliver libdragon's log.
  • The classic main menu background uses different geometry (texel coordinates are 10.5 fixed point, the large tile exceeds TMEM): it animates correctly but not pixel-identically, with zoom narrowed to 0.75 +- 0.05 (original 0.6 +- 0.2) for a steady 40 ms frame.

Rendering fast paths (N64-only)

  • The frame is CPU-bound. The RDP is never waited on.
  • Each tile layer has a cached mesh of its visible window, rebuilt only when the window moves by a whole tile. Animated tiles are kept out and resolved per frame. Records wholly outside the scissor are neither uploaded nor drawn.
  • Tiles reach the RDP as one 16-byte integer record each (RHI::RDP::TileRecord, drawn as PrimitiveType::Points, a form only this backend gets).
  • Debris is packed records too (RHI::RDP::QuadRecord, 32 bytes), written while the particles are updated and batched by texture, palette row, blending and depth. An upright particle is one rectangle, a turned one two triangles at about four times the cost, so snowflakes do not spin, spinning particles under 8 pixels are drawn upright, and the depth of weather particles is rounded to four levels (each depth is a draw; the other consoles with a particle budget round it as well, see TileMap::WeatherDepthStep).
  • Sprites whose window fits TMEM are rounded to the fixed-point grid once and drawn from integers (SubmitSpriteRect()), including the HUD icons. A point-sampled mirrored sprite starts 1/32 texel inside its far edge, as mirrored tiles do.
  • The plain sprite effect is recognized at link time (RdpShaderProgram::DispatchFacts::PlainSprite), and axis-aligned textured instances go straight to a textured rectangle. Rotated or untextured ones take the general path.
  • Text is drawn without shadows (Font::ShadowsEnabled is off), but sprite shadows under the HUD icons and the logo stay.
  • Glyphs are written straight into batched commands (RenderBatcher::BeginDirectBatch()).
  • A canvas keeps what it drew (CANVAS_RETAINED_DRAWS): a rectangle or a string drawn with the same arguments as in the previous frame reuses the command or the glyphs of that frame, whatever changed is drawn as before. The HUD went from 1.6 to 0.9 ms a frame with hearts and from 1.85 to 1.15 ms with the carrots of the Reforged HUD, which wobble. It relies on the dispatch reading the uniform memory of a command in place, so it is on for this backend only.
  • The weapon wheel draws its arcs as one list of lines per color instead of a strip each (a render command costs about a quarter of a millisecond whatever it draws) and leaves out the dark blots behind the icons, a large blended area for a barely visible shade.
  • The collision tree keeps its boxes 2 pixels fat (Collisions::AabbExtension, 0.1 where it was not measured), which stops every bobbing pickup from being reinserted each frame. The same collisions are found.
  • The software lightmap's falloff table is 1 KB (256 steps, rounded): together with the map it has to fit the 8 KB data cache.
  • Both caches of the CPU are direct-mapped (16 KB of instructions, 8 KB of data), so what shares a cache line decides the frame time as much as the code does:
    • The hot code is linked in a fixed order made from a profile ("cmake/n64_text_order.ld"). Make it again when the frame changes a lot.
    • The RDP dispatch is entered at a fixed place of the data cache, chosen at startup so that its stack frames share no line with the state the draw loops use (RdpDevice::Dispatch()). Left to chance, the same build drew the same frame in 16.5 to 20.2 ms.
  • When profiling, compare release builds — layout alone still moves timings by a millisecond.

Audio and video

  • Music plays from converted modules: libopenmpt and libxmp need 0.5–4 MB per module, so the packer translates the .j2b modules into libdragon's .xm64 (only patterns in memory, VADPCM instruments streamed from the cartridge) and pre-renders the three tracks in other formats.
  • Audio costs about 3 ms CPU per frame. Every streamed channel must be VADPCM — a single raw PCM stream limits every mixer round to ~120 samples and roughly doubles the cost. VADPCM's Huffman stage is left off (the CPU would have to undo it).
  • A paused sound effect restarts from the beginning when resumed: the mixer has no paused state and effects have no VADPCM seek points, and libdragon asserts ("invalid VADPCM seeking point") on any other position.
  • Cinematics are MPEG-1, played by libdragon's player (CPU + RSP), which owns the main thread while playing. The port tops audio up once more per frame and holds a frame back while the soundtrack lags, otherwise sound runs at ~0.8x ("nCine/Backends/N64/N64FullMotionVideo.cpp").

Sega Dreamcast

A 200 MHz SH-4 with 16 MB main memory, 8 MB video memory and a PowerVR2 (CLX2): no programmable shading, no hardware scissor, 16-bit texture formats only. Renders through the PVR backend ("Sources/nCine/Graphics/RHI/PVR") on KallistiOS, presented by the Dc window backend in 640x480 RGB565.

Toolchain

KallistiOS and its sh-elf cross-compiler are built from source. There is no prebuilt package.

git clone https://github.com/KallistiOS/KallistiOS.git kos
cd kos

# Build the sh-elf (SH-4) cross-compiler
make -C utils/kos-chain

# The sample configuration matches the paths the toolchain just used
cp doc/environ.sh.sample environ.sh
source environ.sh
make -j $(nproc)

# zlib (required for compressed content) from kos-ports
git clone https://github.com/KallistiOS/kos-ports.git ../kos-ports
make -C ../kos-ports/zlib install

For a non-default install prefix, edit "utils/kos-chain/Makefile.cfg" first, then "environ.sh" so KOS_BASE, KOS_CC_BASE and KOS_PORTS point at the built tree.

For a bootable disc image, mkdcdisc must be on PATH:

git clone https://gitlab.com/simulant/mkdcdisc.git
cd mkdcdisc
meson setup build && ninja -C build
sudo cp ./build/mkdcdisc /usr/local/bin/

Preparing the content tree

The disc is the only medium: no first-run conversion, no writable Cache, and the build authors the content into the image — so the tree must exist before building. Prepare it as in Preparing the game content, but with the dreamcast profile:

# 1. The tool (any desktop build directory already has it)
cmake -B ./build/ -D CMAKE_BUILD_TYPE=Release
cmake --build ./build/ --target AssetPacker --parallel $(nproc)

# 2. Convert with the Dreamcast profile - NOT "--target=console"
./build/Utilities/AssetPacker/AssetPacker ./build/DreamcastContent \
    --source=<path to the original Jazz Jackrabbit 2> --content=./Content --target=dreamcast

# 3. Check that Prebaked.pak exists
ls ./build/DreamcastContent
  • The tree must contain "Prebaked.pak". The Dreamcast packaging does not rename a "Source.pak", so a desktop cache produces a disc that loads nothing and shows a main menu with no episodes. Check for the file, not the directory.
  • Trim before authoring (--originals-only, --skip-non-episode-levels, --video-downscale=N) — the image cannot be changed afterwards. Keep Music: this console plays it (via libxmp, see Limits and known issues).

Building

source <path to KOS>/environ.sh
cmake -B ./build/dreamcast/ -D CMAKE_BUILD_TYPE=Release \
    -D CMAKE_TOOLCHAIN_FILE=${KOS_BASE}/utils/cmake/kallistios.toolchain.cmake \
    -D NCINE_CONTENT_DIR=$PWD/build/DreamcastContent
make -j $(nproc) -C ./build/dreamcast/
  • NCINE_CONTENT_DIR is cached: pass it on the first configure (or re-run CMake with it). Without it the repository's own "Content" is used, which has no episode to play.
  • LTO is force-disabled (it makes sh-elf GCC 15.2 abort), Release uses -O2, and DEATH_USE_FAST_MATH is never applied on this platform.

The build produces "build/dreamcast/jazz2.elf" and, if mkdcdisc was found, "build/dreamcast/jazz2.cdi" with the content at "/cd/Content". The POST_BUILD step:

# 1. Stage the tree under a directory literally named "Content"
cmake -E copy_directory <NCINE_CONTENT_DIR> ./build/dreamcast/cd/Content
# 2. Author the image from the ELF and that directory
mkdcdisc -e ./build/dreamcast/jazz2.elf -d ./build/dreamcast/cd/Content \
    -n "Jazz2 Resurrection" -o ./build/dreamcast/jazz2.cdi

mkdcdisc puts a directory on the disc under its own name and the game looks for "/cd/Content/" — a hand-written mkdcdisc call on "build/DreamcastContent" produces a disc the game cannot read.

Changing the content of a finished image

No KallistiOS toolchain or mkdcdisc is needed to replace the content:

./build/Utilities/AssetPacker/AssetPacker swap-content ./build/dreamcast/jazz2.cdi \
    --content=./build/DreamcastContent

swap-content keeps the bootstrap and executable as they are (1ST_READ.BIN stays scrambled) and rewrites the image around a new Content from a --target=dreamcast conversion. It runs wherever the packer does, and the image keeps its size if the new content fits (usually). The --content= directory becomes Content on the disc whatever its name, and since the image is rebuilt rather than patched, the staging-directory trap above does not apply. See Replacing the content of a disc image. The PlayStation 2 image uses the same command.

Deploying and running

  • Emulator — "jazz2.cdi" boots in Flycast, lxdream or redream.
  • Real hardware — burn the CDI with a tool that handles the Dreamcast multi-session layout, or use an optical drive emulator such as GDEMU/MODE.
  • dc-tool over serial or a Broadband Adapter uploads "jazz2.elf" for fast iteration, but the content is still read from "/cd/Content/", so a disc must be present.

Logs in Flycast: set Debug.SerialConsoleEnabled = yes in "flycast/emu.cfg" while Flycast is not running (it rewrites the file on exit and can revert the setting, which looks like a crash before main()). Startup messages go to the on-screen framebuffer console, not serial, and serial output is block-buffered, so a crash loses everything since the last flush.

Limits and known issues

Memory

  • Main memory is the binding constraint: the heap is roughly 13.8 MB. Exhaustion shows in the log as Out of memory. Requested sbrk_base …, then std::bad_alloc and an abort (the emulator reports only a CPU exception). Video memory reports Out of PVR memory allocating ….
  • Console-only budgets: debris is capped (bursts coarsened, not truncated), the outgoing level is released before the next loads, and PVR texture host copies are RLE-compressed. The "Particle Quality" option in Options > Graphics (Jazz2::ParticleQuality, all platforms) reduces further: Low halves bursts and weather, Off drops debris and weather, High is unrestricted.
  • After every level load the log has a line Memory (level loaded): heap … VRAM … sound RAM … (see nCine::Backends::DcPlatform).

Display and rendering

  • The logical view is 640x480 (not the 720x405 of 16:9 platforms), so it maps 1:1 onto the 4:3 480-line output, at the cost of ~1.4x the pixels (see Jazz2::Rendering::UpscaleRenderPass::DefaultViewWidth).
  • Textures are 16-bit (ARGB4444, or palettized), clipping is geometric (no hardware scissor), and there is no post-processing tier: no rescale filters, the lightmap is combined on the CPU.
  • A scissor covering the whole viewport is ignored (it would clip nothing), but splitscreen and partial menu scissors still clip, and primitives wholly inside a narrower scissor skip clipping.
  • The lightmap's ARGB4444 texture persists. Only the lit spans of this and the previous frame are converted (RHI_LIGHTING_LIT_SPANS) while size and ambient stay unchanged.
  • The lightmap is built at 1/8 of the output resolution (80x60 texels). At 1/4 the torch-lit levels spent 11–18 ms a frame on it and were the only ones below 60 Hz.
  • Weather particles are batched by depth rounded to four levels (each depth is a draw), and the collision tree keeps its boxes 2 pixels fat, as on the Nintendo 64.

Audio

  • Sound effects live in the AICA's own 2 MB sound RAM, not on the heap. Main memory holds the module decoder, three 16 KB buffers per stream, and sounds too long for a channel.
  • Music plays through libxmp (NCINE_WITH_XMP, on by default): a loaded module costs 0.5–4 MB versus libopenmpt's 4.6–12.5 MB, and with libopenmpt the larger levels run out of memory. -D NCINE_WITH_XMP=OFF brings libopenmpt back (both are compiled from source). libxmp cannot read the four .mo3 tracks.
  • Sound effects use AICA wavetable channels (one per mono channel, so stereo samples are de-interleaved on upload), see nCine::AicaAudioDevice. When one has finished is predicted from length and rate — real hardware never clears the key-on bit of a finished one-shot (emulators do). Music uses KallistiOS's snd_stream, of which there are only four.
  • A channel addresses at most 65534 samples (~3 s at 22 kHz). A longer sound that fits after one halving of its sample rate is halved (logged by nCine::AicaAudioDevice::uploadBuffer). One that would need more is kept in main memory and played through a snd_stream handle (shared with music, no pitch changes). Only if that memory is unavailable is it halved further.
  • 8-bit samples are converted to signed on upload: uploaded unsigned they crackle loudly (nearly all original sounds are 8-bit).
  • Panning and attenuation are computed on the CPU. The per-channel low-pass filter is not reachable through KallistiOS, so nothing is muffled underwater.
  • Module music renders at 22050 Hz (the AICA resamples for free) and uses single-precision pow()/log() (see Work the fixed-function consoles leave out).
  • A stream's rate is fixed once started, so pitch changes apply to sound effects only.
  • Streams are stopped during a load and resumed afterwards, so loads are silent rather than looping the last fragment (see nCine::IAudioDevice::BeginBlockingOperation).

Saving

  • Preferences and resumable state go to the first VMU ("/vmu/a1/Jazz2" and "/vmu/a1/Jazz2.resume"). With no card there is nowhere to save (warned at startup, not an error). The level cache is read from the disc.
  • Both files carry a VMS header (descriptions + 32x32 icon) so the file manager lists them. It costs two extra blocks per file (see Jazz2::PreferencesCache::DescribeNextMemoryCardFile). The icon is "Sources/Icons/Dreamcast/Icon.ico" (32x32, 4 bpp, 15 colours + transparency, not animated), converted at configure time by "cmake/ncine_dreamcast_icon.cmake" with no host image tool — replace that file to change it.

Networking

  • Online multiplayer is disabled, but local splitscreen works.

Nintendo Wii

A 729 MHz PowerPC (Broadway) with 24 MB MEM1 and 64 MB MEM2, and the fixed-function Hollywood GPU (16-stage TEV). Renders through the GX backend ("Sources/nCine/Graphics/RHI/GX") on libogc, presented by the Ogc window backend in the console's preferred video mode (PAL 50 Hz or NTSC/EDTV 60 Hz, interlaced or progressive).

Toolchain

# Install devkitPro's pacman, then the Wii group and zlib
sudo dkp-pacman -S --needed wii-dev ppc-zlib

export DEVKITPRO=/opt/devkitpro

ppc-zlib is not part of wii-dev but is required. The toolchain file is "$DEVKITPRO/cmake/Wii.cmake".

Building

cmake -B ./build/wii/ -D CMAKE_BUILD_TYPE=Release \
    -D CMAKE_TOOLCHAIN_FILE=${DEVKITPRO}/cmake/Wii.cmake \
    -D NCINE_CONTENT_DIR=$PWD/build/ConsoleContent
make -j $(nproc) -C ./build/wii/

Besides "build/wii/jazz2.dol" the build stages the Homebrew Channel SD layout:

build/wii/sd/apps/Jazz2/boot.dol
build/wii/sd/apps/Jazz2/Content/…

Deploying and running

  • Real hardware — copy "build/wii/sd/" to the root of an SD card or USB drive and launch from the Homebrew Channel. "apps/Jazz2/meta.xml" is optional.
  • Dolphin — make a FAT32 image from the staging tree and enable the virtual SD card:
truncate -s 512M sd.raw && mkfs.vfat -F 32 sd.raw
mcopy -i sd.raw -s ./build/wii/sd/apps ::/
# Dolphin.ini: [Core] WiiSDCard = True, WiiSDCardPath = <path to sd.raw>
flatpak run org.DolphinEmu.dolphin-emu -e ./build/wii/jazz2.dol -b

Logs: put a USB Gecko in memory-card slot B (SlotB = 7 in Dolphin.ini) and read Dolphin's TCP socket on port 55020. Without the adapter nothing is written. Frame dumps: DumpXFBTarget = True in "GFX.ini" writes every displayed frame as PNG.

Limits and known issues

Display and rendering

  • The logical view is 640x480 on a 4:3 set (not 720x405), ~1.4x the pixels. With widescreen set in the system settings, the view is fitted to 16:9 (640x360) and the TV stretches it (nCine::Backends::OgcGfxDevice::GetDisplayAspect(), reads CONF_GetAspectRatio()).
  • No post-processing tier: no rescale filters, the lightmap is combined on the CPU (skipped in fully lit levels, see Work the fixed-function consoles leave out), converted in one pass into the 4x4-tiled RGBA8 GPU layout, using frsqrte + two Newton steps since the CPU has no square-root instruction.
  • Textures are converted to GX formats (CI8 with hardware TLUT for palettized ones). Effect passes become TEV stages generated from the .shader files.
  • Palette data is byte-swapped on load (big-endian) — keep in mind when comparing palette dumps with desktop.

Audio

  • Music plays through libxmp (NCINE_WITH_XMP, on by default): 0.5–4 MB per module versus libopenmpt's 4.6–12.5 MB, and libopenmpt would also be compiled into the binary (not packaged by devkitPro). libxmp cannot read the four .mo3 tracks. -D NCINE_WITH_XMP=OFF switches back.
  • Sound uses libogc's ASND, not OpenAL: the DSP mixes up to 16 voices at 48 kHz, which is also the engine's source limit (64 on desktop). Panning and attenuation are folded into the per-voice volume on the CPU (AsndAudioDevice::computeVolume()).
  • ASND holds only two buffers per voice, so the stream queue lives in the backend (nCine::AsndAudioDevice::updatePlayers).
  • The DSP reads samples from main memory by DMA (32-byte aligned and padded buffers). There is no separate sound RAM, so sound effects share the heap.
  • No DSP filter stage, so nothing is muffled underwater.

Networking

  • Online multiplayer is disabled, but local splitscreen works.

Nintendo Wii U

Three 1.24 GHz PowerPC cores (Espresso) with 1 GB of memory for applications. There is no OpenGL on the console. The GX2 rendering backend ("Sources/nCine/Graphics/RHI/GX2") draws with the console's R700-class GPU directly: the full shader pipeline, with lighting, blur, water and every rescale shader. It renders on the GX2 context SDL2's video driver (devkitPro's wiiu-sdl2) sets up and presents to the TV and GamePad scan buffers itself.

Input and audio go through SDL2. The result is a native application for the Aroma environment, not a vWii one.

Toolchain

# Install devkitPro's pacman, then the Wii U group, SDL2 and zlib
sudo dkp-pacman -S --needed wiiu-dev wiiu-sdl2 ppc-zlib ppc-libvorbis

export DEVKITPRO=/opt/devkitpro

The devkitpro/devkitppc Docker image has all of it. The toolchain file is "$DEVKITPRO/cmake/WiiU.cmake".

Building

cmake -B ./build/wiiu/ -D CMAKE_BUILD_TYPE=Release \
    -D CMAKE_TOOLCHAIN_FILE=${DEVKITPRO}/cmake/WiiU.cmake
make -j $(nproc) -C ./build/wiiu/

This builds the native GX2 backend. Its shaders are compiled offline and committed in "Sources/Shaders/Generated/Gx2GeneratedShaders.h", so the build does not need CafeGLSL; only changing a shader does (--emit-gx2, see Shader compilation).

The build makes "build/wiiu/jazz2.rpx" and "build/wiiu/jazz2.wuhb", a bundle of the executable, "Content", the icon and the splash screens ("Sources/Icons/WiiU"). A tree prepared with AssetPacker can be bundled instead with -D NCINE_CONTENT_DIR=..., but it is not needed: there is enough memory to convert the original files on the console.

Deploying and running

  • Copy "jazz2.wuhb" to "sd:/wiiu/apps/". Aroma shows every bundle there as an icon on the Wii U Menu, nothing has to be installed.
  • Copy the original Jazz Jackrabbit 2 files to "sd:/wiiu/apps/Jazz2/Source/". They are converted into "sd:/wiiu/apps/Jazz2/Cache/" on the first start, which takes a while. Settings, saves and "Jazz2.log" are written next to them.
  • Cemu (2.6) runs the ".wuhb" too, with its emulated SD card holding "wiiu/apps/Jazz2/Source". It does not evaluate the condition of a trap instruction and never moves past a conditional one (tw/twi), even though it never fires on hardware, and GCC 16 emits those for libstdc++'s checks (the shared_ptr reference count overflow test, for example). The game then hangs with a grey screen at the first one. Replacing the conditional traps in "jazz2.elf" with nop and running elf2rpl and wuhbtool again gives a build Cemu can run. The console is not affected.

Logs: "Jazz2.log" on the SD card, and every line also goes to OSReport(), which Cemu shows with coreinit logging on.

Limits and known issues

  • The frame follows the console's TV output setting: 1920x1080 when the console outputs 1080i or 1080p, 1280x720 for 720p and 854x480 for 480p (the size wiiu-sdl2 gives the TV display). The screen buffer and the main render targets go in MEM1, the console's fast memory, while it has room, and in MEM2 otherwise; if there is no room for a 1920x1080 screen buffer at all, it falls back to 1280x720 and logs a warning. The level itself is still drawn at the Rendering resolution; a bigger screen buffer sharpens the upscale, the rescale shaders and the text. The same frame is shown on the GamePad.
  • With Zoom out and three or four players, the supersampled scene is scaled to the screen with a plain linear filter instead of the antialiasing pass other platforms use, which costs the console about 11 ms per frame at 1080p. Turning on Antialiasing or a rescale mode brings the full pass back, and with it the cost: with four players and Zoom out at 1080p, Antialiasing drops the game from 60 to about 43 fps on the console; with it off, every setup measured there holds 60 fps. The GPU draws one frame while the game prepares the next, so the picture is up to one frame late.
  • Batched sprites (drawn as instances from a uniform block) and tile layers while scrolling run on the console without problems. Cemu's frame rate says nothing about the console's.
  • No online multiplayer, update check or level pack downloads yet. wut provides sockets and devkitPro packages libcurl and mbedTLS for the Wii U, but the port does not enable them (WITH_ONLINE_MULTIPLAYER is off, libcurl is not linked); that needs testing on a console first. Local multiplayer works with any mix of the GamePad, Pro Controllers and Wii Remotes.
  • Asynchronous tracing is off, because the RPX format has no thread-local storage.

Nintendo GameCube

Same code path as the Wii (GX + Ogc backends) on a 486 MHz Gekko and the Flipper GPU, but with 24 MB of RAM and no MEM2. Runs from its own disc, or from an SD card in an SD Gecko (memory-card slot) or SD2SP2 (serial port).

Toolchain

sudo dkp-pacman -S --needed gamecube-dev ppc-zlib

export DEVKITPRO=/opt/devkitpro

ppc-zlib is not part of gamecube-dev. The toolchain file is "$DEVKITPRO/cmake/GameCube.cmake". The disc image is made by AssetPacker, so a host build of it is needed too (any desktop build has one).

Building

cmake -B ./build/gamecube/ -D CMAKE_BUILD_TYPE=Release \
    -D CMAKE_TOOLCHAIN_FILE=${DEVKITPRO}/cmake/GameCube.cmake \
    -D NCINE_CONTENT_DIR=$PWD/build/ConsoleContentGameCube \
    -D GAMECUBE_ASSETPACKER_EXECUTABLE=$PWD/build/Utilities/AssetPacker/AssetPacker
make -j $(nproc) -C ./build/gamecube/

Prepare the tree with --target=gamecube (LZ4 sprites/tilesets, see LZ4 sprite sheets and tilesets, and cinematics re-encoded into Jazz2::VideoFormat). A console tree works but its intro falls far behind the music. The build stages the content both as a disc image and as an SD card layout:

build/gamecube/jazz2.iso                 # bootable disc image
build/gamecube/sd/Jazz2/Jazz2.dol
build/gamecube/sd/Jazz2/Content/…

Without GAMECUBE_ASSETPACKER_EXECUTABLE (or AssetPacker on PATH) only the SD layout is staged. The staged Content is cleared before each copy.

The disc image

AssetPacker create-image makes the image (see The GameCube disc image): an ISO 9660 volume with the executable and Content, plus the disc header and an apploader in the system area, built from "Sources/nCine/Backends/Ogc/GameCubeApploader.c" (none ships with the toolchain). Game ID GJJEJR (GAMECUBE_GAME_ID, no retail game, so Dolphin applies no game-specific settings), region NTSC-U. AssetPacker swap-content (also in its web version) replaces the content of a finished image without the toolchain.

The disc is read through the game's own driver (OgcDvd, mounted as dvd:, since libogc's ISO 9660 driver leaks and resets the drive). Content is searched in this order (ContentResolver::InitializePaths()):

  1. Content next to the executable (when a loader started it from SD).
  2. The disc, if it is this game's and the drive is ready — so disc content wins over a stale tree on a card.
  3. Jazz2/Content on each SD card: sd: (SD2SP2), then carda: and cardb: (SD Gecko).
  4. The disc again, resetting and spinning up the drive.

If none is found the boot console says so and stops. With SD content, settings, resumable state, cache and log go to the card. With disc content, saves go to the first usable memory card (slot A, then B): Jazz2.config and Jazz2.resume, a few 8 KB blocks each, with icon and comment (see OgcMemoryCard.h). With no memory card nothing is saved.

Deploying and running

  • Dolphin — boot "build/gamecube/jazz2.iso" (Dolphin has no GameCube SD adapter, so the image is the only way). Slot A holds a memory card by default ("GCI Folder" saves .gci files under "GC/USA/Card A/"). Keep slot B on "USB Gecko" for the log (trace goes to EXI channel 1 = slot B).
  • Real hardware, SD card — copy "build/gamecube/sd/" to a card in an SD2SP2 or SD Gecko (either slot) and start "Jazz2/Jazz2.dol" from Swiss.
  • Real hardware, disc image — an optical drive emulator (GCLoader, CubeODE, FlippyDrive) or a burned disc on a console that boots them. Untested: only known to boot in Dolphin. Don't load the image from a card via Swiss (its disc-read patching does not fit this game). Use the SD layout.

Limits and known issues

Everything in Limits and known issues applies, plus:

  • Memory is much tighter: 24 MB, no second pool. The Dreamcast's console budgets apply, ASND keeps every decoded sound effect in main memory, and the episode list draws no backdrops (over 5 MB).
  • No Bluetooth: only GameCube controllers (the Wii build also links wiiuse and bte for Wii Remotes).
  • Dolphin's default DSP HLE sometimes raises ASND's DSP interrupt without its mail, which would hang libogc's handler forever, so the ASND backend lets such an interrupt pass (AsndAudioDevice.cpp). No effect on real hardware.

Nintendo 3DS

A 268 MHz ARM11 MPCore (804 MHz with the L2 cache on a New 3DS, requested at startup) with 64 MB of application memory (more on a New 3DS, and the first log line reports how libctru split it between the heap and the linear heap) and a DMP PICA200 driven through citro3d. The port renders through the PICA backend ("Sources/nCine/Graphics/RHI/PICA"), presented by the Ctr window backend on the top screen at 400x240. The bottom screen is a text console: startup messages until the renderer takes over, warnings and errors afterwards.

The only programmable stage is a passthrough vertex shader ("Sources/Shaders/Pica/Sprite.v.pica", assembled by picasso). Quads are transformed on the CPU, effects come from ShaderCompiler's pica fixed-function tables (see Fixed-function blocks) as texture-combiner programs, and lighting is the software lightmap.

Toolchain

From devkitPro's pacman repository: the 3ds-dev group (devkitARM, libctru, citro3d, 3ds-cmake, and the 3dstools, picasso and bin2s packaging uses), 3ds-zlib for the content, and 3ds-curl + 3ds-mbedtls for the update check and the online server list:

sudo dkp-pacman -S --needed 3ds-dev 3ds-zlib 3ds-curl 3ds-mbedtls

export DEVKITPRO=/opt/devkitpro
export DEVKITARM=$DEVKITPRO/devkitARM
export PATH=$DEVKITPRO/tools/bin:$DEVKITARM/bin:$PATH

Root is not needed: the packages are plain tarballs ("https://pkg.devkitpro.org/packages/", listed in the dkp-libs and dkp-linux databases) that bsdtar extracts into any prefix. Point DEVKITPRO at the opt/devkitpro inside it. The server answers generic download clients with 403 — send pacman's User-Agent (pacman/6.1.0 (Linux x86_64) libalpm/14.0.0 works).

The toolchain file "$DEVKITPRO/cmake/3DS.cmake" defines NINTENDO_3DS and __3DS__, links through 3dsx.specs and provides ctr_add_shader_library(), ctr_generate_smdh() and ctr_create_3dsx().

  • Threads come from devkitARM's libsysbase over libctru's LightLock/CondVar, so find_package(Threads) succeeds and NCINE_WITH_THREADS stays on. sched_yield() is supplied by "Sources/nCine/Backends/Ctr/CtrLibcCompat.cpp". Scheduling parameters and affinity are absent and unused (the application sees one core).
  • libctru's sub-headers have no extern "C", only the umbrella <3ds.h> wraps them. C++ code that includes <3ds/svc.h> or <3ds/synchronization.h> directly must wrap the include itself, or the link fails on mangled symbols.

Module music is libxmp, built from source by the configure step, as libopenmpt is too heavy for this CPU.

Building

export DEVKITPRO=/opt/devkitpro
export DEVKITARM=$DEVKITPRO/devkitARM
export PATH=$DEVKITPRO/tools/bin:$DEVKITARM/bin:$PATH
cmake -B ./build/3ds/ -D CMAKE_BUILD_TYPE=Release \
    -D CMAKE_TOOLCHAIN_FILE=$DEVKITPRO/cmake/3DS.cmake \
    -D NCINE_CONTENT_DIR=$PWD/build/ConsoleContent
cmake --build ./build/3ds/ --parallel $(nproc)

The console cannot convert the original data itself, so pass the tree from the AssetPacker's console profile (see Preparing the game content). Without it the build falls back to the repository's Content, which boots into the menu but has no levels.

Outputs: "build/3ds/jazz2.elf", "build/3ds/jazz2.3dsx", "build/3ds/jazz2.smdh" (Homebrew Launcher icon and titles) and the staged SD card layout:

build/3ds/sdmc/3ds/Jazz2/Jazz2.3dsx
build/3ds/sdmc/3ds/Jazz2/Jazz2.smdh
build/3ds/sdmc/3ds/Jazz2/Content/…

Content is read from "sdmc:/3ds/Jazz2/Content/". The cache, configuration, saves and Jazz2.log are written next to it (see Jazz2::ContentResolver).

Deploying and running

  • Real hardware — copy "build/3ds/sdmc/3ds/Jazz2" to "/3ds/Jazz2" on the SD card and start it from the Homebrew Launcher (needs custom firmware or another way to run unsigned homebrew). 3dslink -a <console IP> build/3ds/jazz2.3dsx sends a fresh build to the launcher's network loader. The content must already be on the card.
  • Azahar (Citra's continuation) — azahar -w build/3ds/jazz2.3dsx. Copy the staged "3ds/Jazz2" tree into its virtual SD card "user/sdmc/" (flatpak: "~/.var/app/org.azahar_emu.Azahar/data/azahar-emu/sdmc/"). "sdmc:/" resolves against that card, not the .3dsx directory. Networking needs no setup, soc:u runs on the host's sockets.

Logs: the trace goes to svcOutputDebugString(), which Azahar writes to "user/log/azahar_log.txt" under Debug.Emulated — hidden by the default filter. Set log_filter=*:Info Debug.Emulated:Debug in its qt-config.ini. Jazz2.log on the virtual card is flushed as it is written.

Azahar renderers:

  • OpenGL needs OpenGL 4.3, Vulkan a real driver. Without either (e.g. a VM), LIBGL_ALWAYS_SOFTWARE=1 gives it Mesa llvmpipe (a 4.5 context, full speed).
  • Its own software renderer (graphics_api=0) is correct but runs the menu at about 1 fps — screenshots only.

Limits and known issues

Display and rendering

  • One 400x240 view on the top screen: no stereoscopic 3D, nothing on the bottom screen but the console.
  • Textures are sampled bottom-up (v = 0 reads the last row in memory), so PicaTexture::BuildPage() stores the source's first row last. Render targets need no extra flip: PicaDevice::ApplyDrawTarget() sends a pass's first raster row to v = 0, so targets are top-down like on every other backend (see nCine::RHI) and non-power-of-two padding lies below the image.
  • No palette textures. R8/RG8 (palette-indexed) stores are baked to RGBA4 on the CPU per palette row, two baked rows kept per texture (PicaTexture::EnsureBakedStore()). A sprite drawn with three or more palette rows in one frame rebakes on every draw (logged once).
  • Textures are 8..1024 texels, powers of two, 8x8 Morton-tiled, in the linear heap. Larger ones are paged as on the GE. The hardware wraps at the padded size, so repeating textures must be powers of two (as on the PSP). Stores and vertex buffers must be written back with GSPGPU_FlushDataCache() before the GPU reads them. Vertices are flushed once per submitted command list (PicaDevice::FlushPendingWrites()), not per draw — that GSP request is expensive.
  • Triangle strips join the batch as triangle lists, so the warped textured background batches like quads. The PICA200 repeats the 256x256 target it samples in hardware, so each band is one strip, with the horizon tint folded in by the combiner (see Fixed-function blocks).
  • 16-bit colour everywhere: RGB565 screen target, RGBA4/RGB565 textures, a 4-bit lightmap. The banding is the hardware's.
  • A mid-frame clear splits the command list. C3D_RenderTargetClear() is a transfer-engine fill, not a command, so PicaDevice::Clear() calls C3D_FrameSplit() first. A scissored clear is drawn as a quad.

Audio and math

  • The "Sample Rate" option in Options > Sounds exists as on the PSP. The DSP resamples to its own 32728 Hz, so the presets go up to that.
  • The lighting approximation and sinApprox() use the PSP's values, untuned on hardware. The port was verified in Azahar.

System services

  • Text input uses the system swkbd applet, which blocks its thread and must not run inside a citro3d frame. MainApplication::ShowScreenKeyboard() only records the request. UpdateScreenKeyboard() runs the applet after the frame is presented (the game pauses) and replaces the field's text, as on the PSP and Vita. Afterwards the pad reads idle until every button has been released once.
  • Asynchronous tracing is off, as on the PSP, so the logs are complete when the process dies.

Networking

  • Online multiplayer works, over ENet only. libctru's sockets (soc:u) have getaddrinfo() and poll(). The vendored enet.h only routes sendmsg() and recvmsg() through sendto() (buffers gathered into one datagram) and recvfrom(). ENET_IPV6=0 (no in6_addr in libctru) and WITH_WEBSOCKET is off (no "netinet/ip.h"). CtrPlatform::Initialize() lends the service a page-aligned 1 MB buffer with socInit() before any socket opens, and Shutdown() takes it back. The WLAN is the system's business: an offline console simply fails to connect. In Azahar a server on 127.0.0.1 is the host.
  • A failed socket call is not treated as a lost connection. The one soc:u buffer is shared by every socket and HTTPS request, so transient errors happen on hardware (not in Azahar). The 3DS arms of enet_socket_send() and enet_socket_receive() treat every error except EBADF, ENOTSOCK and EFAULT as nothing sent/received. ENet resends reliable data and the peer timeout still catches a dead server. The first 16 errors are logged with their errno.
  • HTTPS needs the CA bundle staged next to the content. devkitPro's libcurl (mbedTLS) defaults to "sdmc:/config/ssl/cacert.pem". The build downloads the bundle at configure time and stages it as "Content/cacert.pem", where ApplyPlatformWebRequestOptions() points libcurl (as on the PSP and Vita). Without it the update check and server list fail with an mbedTLS -0x3E00 error naming the default path. The console clock is real time (unlike pspdev's, see Limits and known issues). When porting further: WebRequest.cpp picks its libcurl backend from an explicit target list, and a missing target silently gets no backend.

PlayStation Portable

A 222 MHz MIPS Allegrex (raised to 333 MHz at startup) with 32 MB of memory (24 MB usable, 64 MB on the 2000/3000 models) and a Graphics Engine driven through sceGu. The port renders through the GU backend ("Sources/nCine/Graphics/RHI/GU"), presented by the Psp window backend at 480x272.

Toolchain

pspdev ships prebuilt for Linux, macOS and Windows, builds from source with build-all.sh, and is the pspdev/pspdev container image (used by CI):

# Prebuilt SDK (see https://github.com/pspdev/pspdev/releases)
tar -xJf pspdev-<platform>.tar.xz -C ~/sdk

export PSPDEV=~/sdk/pspdev
export PATH=$PSPDEV/bin:$PATH

The SDK includes zlib, libvorbis and an OpenAL Soft with a sceAudio backend. Further ports install with psp-pacman. The toolchain file is "$PSPDEV/psp/share/pspdev.cmake" (psp-cmake passes it automatically). Keep $PSPDEV/bin on PATH: packaging runs psp-fixup-imports, mksfoex and pack-pbp from there.

Building

export PSPDEV=~/sdk/pspdev
export PATH=$PSPDEV/bin:$PATH
cmake -B ./build/psp/ -D CMAKE_BUILD_TYPE=Release \
    -D CMAKE_TOOLCHAIN_FILE=$PSPDEV/psp/share/pspdev.cmake \
    -D NCINE_CONTENT_DIR=$PWD/build/ConsoleContent
make -j $(nproc) -C ./build/psp/

Release compiles with -O2 as on the other consoles (the FPU is single-precision only). The build produces "build/psp/jazz2.elf" and stages the memory-stick layout under "build/psp/ms0/":

build/psp/ms0/PSP/GAME/Jazz2/EBOOT.PBP
build/psp/ms0/PSP/GAME/Jazz2/Content/…

create_pbp_file() packs EBOOT.PBP from the stripped ELF with MEMSIZE=1 in its SFO, which requests the extra memory of the 2000/3000 models.

Deploying and running

  • Real hardware — copy "build/psp/ms0/PSP/GAME/Jazz2" onto the memory stick at exactly that path. Needs custom firmware or another way to start unsigned homebrew.
  • PPSSPP — copy the same directory into the emulator's configured memory stick and start it from the game list.

Logs: the trace reaches PPSSPP's log at info level, prefixed "I[PRINTF]: stdout:" — use --loglevel=4 --log=FILE. For the flatpak the log path must be sandbox-writable (--filesystem=<dir>). Jazz2.log next to the EBOOT is flushed only on a clean exit.

The game raises the CPU to 333 MHz and installs its HOME-button callback before anything else can fail, so the console always has a way out.

Limits and known issues

Crashes, memory and threads

  • FPU exception traps are disabled, and must stay so. PspDisableFpuTraps() (MainApplication.cpp) clears the FCSR enable bits (bits 7-11, plus the cause and sticky-flag fields) at startup and on every engine thread (FCSR is per-thread). With traps armed, a float division by zero kills the process instantly: all threads gone, nothing logged, a frozen screen for about ten seconds and C1-2858-3 on a Vita running Adrenaline. Divisors from level data are still guarded (Jazz2::Actors::Solid::Bridge).
  • Compute animation frames through Jazz2::GraphicResource::GetFrameForTime(), which returns the first frame for a static image. animTime * FrameCount / AnimDuration divides by zero there. ActorBase::ActorRenderer::UpdateAnimation() guards zero-duration looping animations. Code merely sloppy on a desktop can be fatal here without a log. Localize such a crash by enabling parts in stages and logging each.
  • A GE store must not be freed while a display list still references it. Lists run only at sceGuFinish() in GuDevice::PresentFrame(), so GuDevice::SyncBeforeStoreRelease() kicks the list and waits for the GE before GuTexture frees a store (RefreshGeStore(), FreeGeStores(), the destructor), and EnsureList() opens a fresh one. Otherwise sceGuSync() hangs and the firmware kills the process (same freeze and C1-2858-3, no log).
  • Main memory is tight. The heap is the whole user partition (PSP_HEAP_SIZE_KB(-1)) and a full level leaves a few hundred kilobytes, so even a second 64 KB streaming vertex buffer may fail. With -fno-exceptions a failed operator new is a bare abort(). The std::set_new_handler from nCine::Application::InitCommon() logs a fatal line first (on every console). Large true-colour tilesets do not fit: the LayerFX test level (Sources/Jazz2/Tests/LayerEffects, a 9.6 MB 32-bit tileset) loses tiles from its green screen on, as 512 KB atlas-page stores fail to allocate. PPSSPP's allocator leaves more room — check memory on hardware.
  • Palette-indexed fonts are kept on a palette change (with RHI_CAP_PALETTED_TEXTURES they resolve colours from the live palette). Jazz2::ContentResolver asks Jazz2::UI::Font::IsPaletteIndexed(), saving a texture reload during level load.
  • The GE display list is 32 KB (the busiest frame uses 3.7 KB). sceGu does not bounds-check it, so GuDevice::PresentFrame() warns once if a frame passes three quarters.
  • Threads are on, over pspdev's pthread-embedded. pthread_setname_np and CPU affinity are compiled out, as on the libogc consoles. pthread_t is a pointer (use reinterpret_cast), and stack information comes from sceKernelReferThreadStatus().
  • Thread stacks are 64 KB, and raising them is not free. sceKernelCreateThread allocates stacks from what the firmware kept back, which holds one 256 KB stack but not two. The second creation fails with NO_MEMORY and the thread silently never runs. Even at 64 KB the multiplayer client thread did not fit next to the audio decoder and the discovery thread, so the server list stops discovering (Jazz2::Multiplayer::ServerDiscovery::Stop()) before it connects, and a client whose thread cannot start reports the failure.
  • Spinlocks sleep here. The kernel has strict priorities and no time-slicing, so a busy-wait deadlocks against a descheduled holder, so Death::Threading::Spinlock sleeps (sceKernelDelayThread(50)) while contended. The multiplayer client thread raises itself above the main thread's priority 32 (sceKernelChangeThreadPriority(0, 24)), otherwise pings are 200-300 ms. The console's WLAN power saving (a system setting) adds latency too.

Rendering

  • Textures are limited to 512 pixels per axis. Larger atlases are split into pages with per-primitive page selection. Palettized textures use the hardware CLUT, only one of which is resident at a time, so the palette is part of the batch key.
  • The GE has no post-texture additive term and no combiner output scale: an offset_color pass expands into a modulated draw plus an additive silhouette, and the MODULATE_X2/MODULATE_X4 presets are rejected for this target.
  • Line strips are expanded into coverage quads, not drawn as GU_LINE_STRIP: a triangle pair per segment, half a pixel to each side, widened by the slope's Manhattan factor, as on the PowerVR (see Limits and known issues). They batch with the frame's other triangles, and the weapon wheel skips its four half-pixel shadow segments here (see Jazz2::UI::HUD::DrawWeaponWheel()).
  • The race minimap's track is rasterized on the CPU (the fixed-function tier has no mesh-sprite program): Jazz2::UI::Multiplayer::MpHUD::RefreshMinimapTrackTexture() renders it once into an alpha mask, drawn as two sprites (track and shadow).
  • Dynamic lighting is splatted on the VFPU. The PSP arm of CombineRenderer::PrepareSoftwareLighting() is inline VFPU assembly, four texels per instruction, and must run on the main thread, the only one with the VFPU (PSP_MAIN_THREAD_ATTR). Other consoles use the scalar path in "Rendering/SoftwareLightSplat.h". Ring lights (Jazz2::LightEmitter::RingRadius) use SplatRingVfpu() here, SoftwareLighting::SplatRing() elsewhere.

Audio and math

  • Module music plays through libxmp. NCINE_WITH_OPENMPT is forced off — libopenmpt's first module load takes about 29 seconds on this CPU — and NCINE_WITH_XMP is on by default. libxmp reads the original .j2b modules directly, but not MO3, so the four .mo3 tracks are silent. Its double-precision hot paths are replaced (see Work the fixed-function consoles leave out).
  • Audio mixes at 44100 Hz by default, and the "Sample Rate" option in Options > Sounds can halve it (22050 or 44100 Hz, stored in Jazz2::PreferencesCache::AudioSampleRate, applied through nCine::IAudioDevice::SetMixingFrequency()), halving the mixer's and the module decoder's cost. nCine::PspAudioDevice mixes at that rate and linearly upsamples below 44100 Hz. The decoder renders at nCine::IAudioDevice::GetNativeFrequency(). Effects switch at once, music when the next stream opens.
  • This libm is very slow — sinf() costs about 13.5 us. Appearance-only math (flicker, pulse, orbit) goes through nCine::sinApprox() / nCine::cosApprox() (331 ns, within 0.0014), which substitute only on the consoles because on x86-64 the library is faster. Avoid std::floor() too (a real jal floorf). The remaining calls go to an exact replacement (see Work the fixed-function consoles leave out).
  • The underwater and pause low-pass filters are absent — the mixer has no filter stage, like the other software-mixing consoles.
  • The Media Engine is not used. pspdev's libme-core needs custom firmware, reports the core unavailable under Adrenaline (no ME firmware image) and hangs PPSSPP in kinit(). Code touching the ME must first test for the emulator with sceIoDevctl("kemulator:", 0x03, ...), which succeeds only there.

System services

  • The C library's clock is replaced. pspdev's libcglue implements _gettimeofday() (behind time(), gettimeofday() and std::chrono::system_clock) as seconds since midnight, i.e. 1 January 1970, so mbedTLS rejected every certificate as not yet valid — and pspdev's libcurl (7.64.1 on mbedTLS 2.28) reports it without detail. "Sources/nCine/Backends/Psp/PspLibcCompat.cpp" defines _gettimeofday() from the RTC tick, overriding libcglue's.
  • No timezone in the C library, so localtime() is gmtime(). GetLocalTimeZoneOffset() (DateTime.cpp) gets the offset, daylight saving included, by passing one tick through sceRtcConvertUtcToLocalTime(), and GetLocalTm() applies it.
  • HTTPS needs its own CA bundle. The configure step downloads curl.se's cacert.pem and stages it under Content/, as on the Vita. "Sources/Jazz2/PlatformWebRequest.h" points CURLOPT_CAINFO at it and clears CURLOPT_CAPATH, because mbedTLS reads the default directory (/etc/ssl/certs) first and fails on it. To debug a failed verification, route CURLOPT_DEBUGFUNCTION into the trace.
  • Text is entered through the firmware's on-screen keyboard. nCine::MainApplication::ShowScreenKeyboard() opens the modal sceUtility OSK and nCine::MainApplication::UpdateScreenKeyboard() collects the string. nCine::RHI::GU::GuDevice::PresentFrame() refreshes the dialog between list completion and the flip, and nCine::Backends::PspInputManager reports the pad idle while it is open (else the confirming Cross also fires the menu item behind it). The status call returns an error, not "none", when no keyboard was started, so checks match dialog states explicitly.
  • The PSPSDK stub libraries must not be linked twice. psp-gcc's *lib spec already appends -lpsputility -lpsprtc -lpspnet_inet -lpspnet_resolver -lpspsdk -lpspmodinfo -lpspuser. Adding any of them to target_link_libraries splits their stubs, psp-fixup-imports reports "could not fixup imports, stubs out of order", and syscalls such as sceNetInetSocket() end up calling something else.

Networking

  • Online multiplayer works, over ENet only. WITH_WEBSOCKET is forced off (pspdev has neither "netinet/ip.h" nor "poll.h") and ENET_IPV6=0 (sceNetInet has no IPv6). The vendored "Sources/Dependencies/enet/enet.h" supplies the poll(), getaddrinfo() and getnameinfo() libcglue lacks, over select() and gethostbyname()/gethostbyaddr(). Non-blocking sockets use setsockopt(SO_NONBLOCK), since fcntl() does not reach the firmware's sockets, and receiving uses recvfrom() (see Deploying and running).
  • Ad hoc (local wireless) multiplayer is available next to Wi-Fi. Peers are MAC address + port over PDP sockets (sceNetAdhocPdp*), and a session is a group found by scanning. It is a second arm of ENet's socket functions (enet_psp_set_adhoc()), where an ENetAddress host indexes a table of seen MAC addresses, written AA:BB:CC:DD:EE:FF. nCine::Backends::PspNetwork::AdhocBegin() drops the access point and brings up sceNetAdhoc/sceNetAdhocctl. The menus switch modes through Jazz2::Multiplayer::NetworkManagerBase::SetAdhocMode().
    • Hosting: the Connection row of Create Server picks Wi-Fi or ad hoc. The group is named after the server (8 alphanumeric characters, see nCine::Backends::PspNetwork::MakeAdhocGroupName()).
    • Joining: Left/Right in Connect To Server toggles the mode. Jazz2::Multiplayer::ServerDiscovery then lists scanned groups, and an endpoint is GROUP/MAC.
    • Ad hoc groups are visible only to other PSPs (and Vitas running Adrenaline). An ad hoc server is not published anywhere.
  • The access point is joined on demand. PspNetwork::Initialize() ("Sources/nCine/Backends/Psp/PspNetwork.cpp") loads the network PRXes at startup. PspNetwork::ScopedConnection, held by each network consumer on its own thread, joins and waits for DHCP. The association is reference counted. The last release starts a 30 second grace period, ended by PspNetwork::Update() once a frame. The infrastructure modules stay loaded (unloading them under a live libcurl session is unsafe).
  • The access point comes from the saved connections. The slots under Network Settings are probed and the first existing one is used (deleting a connection leaves its slot empty). The Vita's PSP emulator (Adrenaline, ARK-4) saves none, so the connect automatically profile, configuration 0, is used instead. A real console with nothing saved refuses it and reports that no connection is configured.
  • Local discovery uses the IPv4 broadcast address 255.255.255.255 (TryCreateLocalSocket()). Desktop builds use ff02::1 multicast plus an AF_INET broadcast socket (TryCreateLocalBroadcastSocket(), and the multicast one is IPV6_V6ONLY since they share a port), so console and desktop find each other. Jazz2::UI::Menu::ServerSelectSection merges answers with the same identifier into one entry with |-joined endpoints.

PlayStation 2

A 294 MHz MIPS R5900 "Emotion Engine" with 32 MB of main memory and a Graphics Synthesizer whose 4 MB of local memory is the frame buffer, texture cache and palette store at once. The port renders through the GS backend ("Sources/nCine/Graphics/RHI/GS"), presented by the Ps2 window backend in NTSC 640x448.

Toolchain

Use the ps2dev/ps2dev container image, which the recipe below assumes. It ships no CMake, so derive one:

FROM docker.io/ps2dev/ps2dev:latest
RUN apk add --no-cache cmake make git python3 bash xorriso

Preparing the content tree

The console boots from a read-only disc with no first-run conversion and nothing staged into Cache/, so the tree must be complete before the image is authored. Prepare it as in Preparing the game content, with the ps2 profile:

# 1. The tool (any desktop build directory already has it)
cmake -B ./build/ -D CMAKE_BUILD_TYPE=Release
cmake --build ./build/ --target AssetPacker --parallel $(nproc)

# 2. Convert - the original game data and the game's own content are named separately
./build/Utilities/AssetPacker/AssetPacker ./build/ConsoleContentPs2 \
    --source=<path to the original Jazz Jackrabbit 2> --content=./Content --target=ps2

# 3. Prebaked.pak is what makes it a prepared tree
ls ./build/ConsoleContentPs2

Pass the result as NCINE_CONTENT_DIR on the first configuration of the build directory. The packaging step assembles the disc under "build/ps2/cd/" and authors the image:

build/ps2/cd/SYSTEM.CNF     # BOOT2 = cdrom0:\JAZZ2.ELF;1, VER, VMODE = NTSC
build/ps2/cd/CDFS.IRX       # copied from the SDK; loaded at startup so newlib can see the disc
build/ps2/cd/JAZZ2.ELF      # the stripped executable
build/ps2/cd/Content/…      # NCINE_CONTENT_DIR, with "Source.pak" renamed if it has one
xorrisofs -quiet -iso-level 2 -l -J -V JAZZ2 -o ./build/ps2/jazz2.iso ./build/ps2/cd

mkisofs and genisoimage are accepted instead, with the same options. ISO 9660 level 2 with -l limits file names on the disc to 31 characters — mind this for custom levels or tilesets.

"Music" belongs on the disc: the soundtrack plays through libxmp (see Limits and known issues).

Running from a USB stick or an MX4SIO SD adapter

A USB stick in a front port or an MX4SIO adapter (an SD card on a controller port) work as alternatives to the disc, with the same build: the game looks for a content tree on them at startup and then reads and writes everything there (a memory card is too small for the level cache). Two layouts are looked for, in this order:

  • A Content directory next to the executable, on any device and in any directory, taken from argv[0] (see nCine::Backends::Ps2Storage::SetBootPath()).
  • Games/Jazz2/ on a mounted unit, so the tree does not collide with a loader's own APPS, DVD and CFG (the same layout as the Switch's "sdmc:/Games/Jazz2/").
mass0:/Games/Jazz2/JAZZ2.ELF      # wherever the loader is pointed at; this is the tidy place for it
mass0:/Games/Jazz2/Content/…      # what the probe looks for
mass0:/Games/Jazz2/Cache/…        # created by the game, unlike on a disc
mass0:/Games/Jazz2/Jazz2.config   # likewise

Units mass0: to mass3: are probed in order. The IOP modules needed — bdm, bdmfs_fatfs (FAT12/16/32 and exFAT), mx4sio_bd, usbd + usbmass_bd, and audsrv — are linked into the executable, since a device's only driver cannot be read from it (see nCine::Backends::Ps2Modules).

nCine::Backends::Ps2Storage only brings the modules up and reports which units mounted. The directory name and the Content/Cache/Source layout live in Jazz2::ContentResolver::InitializePaths(). A build running from removable storage writes Jazz2.log next to its content — the only practical way to read a trace without a serial cable. From a disc no log is written (the memory card is no place for one).

Building

cmake -S . -B build/ps2 -DCMAKE_TOOLCHAIN_FILE=$PS2SDK/ps2dev.cmake \
    -DCMAKE_BUILD_TYPE=Release -DNCINE_STRIP_BINARIES=ON \
    -DNCINE_CONTENT_DIR=$PWD/build/ConsoleContent
cmake --build build/ps2 -j$(nproc)

The toolchain file defines PLATFORM_PS2, which pins NCINE_PREFERRED_RHI to GS. NCINE_CONTENT_DIR is cached, so set it on the first configuration (see Preparing the content tree). The build produces a stripped jazz2.elf and a bootable jazz2.iso with the layout above. Source.pak is renamed to Prebaked.pak so the game sees a prepared tree, and nothing goes into Cache/.

Without an ISO author on PATH at configure time the build prints xorrisofs/mkisofs not found, bootable ISO image will not be created and produces only the ELF. That boots in PCSX2 with -elf, but with no disc there is no content — the game reads everything from "cdfs:/".

Changing the content of a finished image

As on the Dreamcast, the content can be replaced without rebuilding the image:

./build/Utilities/AssetPacker/AssetPacker swap-content ./build/ps2/jazz2.iso \
    --content=./build/ConsoleContent

swap-content keeps SYSTEM.CNF, the executable it names and the .IRX modules as they are and rewrites the file system around the new Content. The image is resized to fit. It always writes a Joliet hierarchy. See Replacing the content of a disc image.

Deploying and running

Burn jazz2.iso to a disc, or load it in PCSX2. A headless run needs the setup wizard marked complete and a BIOS filename set in its INI, EnableEEConsole on to see any output, and a renderer the host GPU can create:

pcsx2-qt -batch -nogui -earlyconsolelog -logfile run.log jazz2.iso

Logs: the trace goes to the Emotion Engine's SIO transmit register (0x1000F180), including the early CDVD bring-up messages from MainApplication::Run(). PCSX2 captures it as EE console output. On hardware a serial cable picks it up.

Without a cable the same lines appear on the television (PS2SDK's libdebug console, opened before the IOP is touched) until Ps2GfxDevice logs "Handing the display over to the renderer". Every IOP step that can stall a boot (disc wait, CDFS.IRX, memory card, LIBSD and audsrv, the MX4SIO probe) runs before that, so the last line shown names the stuck step. A hang after it points at renderer setup or content loading. Report the last lines shown when a boot stops.

Before the console exists, solid screen colours mark the earlier stages (Ps2BootMarker() in "MainApplication.cpp", via PMODE = 0 and BGCOLOR). A screen stuck on one of them names the stage that did not come back:

ScreenSet when
RedStatic initialization begins
Greenmain() reaches MainApplication::Run()
BlueThe trace system is up and the boot console is about to open
BlackNever — none of the executable ran: the loader, the file or the video signal

Limits and known issues

Display and rendering

  • Local memory is the binding constraint. The 640x448 PSMCT16 display buffer, render-target reserve and CLUT slab leave about 2816 KB of texture cache. A frame's working set fits, a whole level's sheets do not, so textures stream on transitions and a busy level still reports allocation failures. The allocator hands out whole 8 KB pages, because the swizzle within a page depends on the pixel storage mode.
  • The picture is composed for 4:3, not for 640x448. An NTSC pixel here is a seventh taller than wide. Ps2GfxDevice::GetDisplayAspect() reports that and the view is fitted to it. The view is 597x448, so nothing is resampled vertically (see Jazz2::Rendering::UpscaleRenderPass::DefaultViewWidth, which raises the bound from the 16:9 720x405 of other platforms).
  • The GS has no post-texture additive colour term and no combiner output scale: an offset_color pass expands into a modulated draw plus an additive silhouette (via a white-RGB CLUT, see GsDevice::AcquireCoverageClutForOffset()), and the MODULATE_X2/MODULATE_X4 presets are rejected for this target.

Audio

  • Sound goes through audsrv, the IRX that owns the SPU2 on the IOP. The EE only hands it finished PCM (see nCine::Ps2AudioDevice).
    • Its ring buffer is small (about 50 ms at the default 22050 Hz, reported in the trace) and there is no mixer thread, so a long frame is heard as a repeat of the last buffer. Anything that blocks the main thread longer (a level load, the episode list) must call nCine::IAudioDevice::BeginBlockingOperation() first, which stops the stream. Gameplay below about 19 fps still repeats.
    • Music is decoded on the main thread in 1 KB slices during the vertical-blank wait (nCine::IAudioDevice::RunIdleWork()). A chunk unfinished after twelve frames is decoded inside the frame. libxmp's double-precision hot paths (soft-float on the EE) are replaced (see Work the fixed-function consoles leave out).
    • NCINE_WITH_OPENMPT is forced off (libopenmpt's to_chars(char*, char*, const double&) is ambiguous against PS2SDK's newlib), so the soundtrack is libxmp's (on by default), which cannot read the 4 .mo3 tracks of the 56.

Threads and saving

  • Threads are off, so multiplayer (including local splitscreen) is compiled out and asset loading is synchronous.
  • Saves need writable storage. Preferences and progress go to a memory card (mc0:/Jazz2/, the first usable slot, with the icon.sys the console's browser needs or it shows "Corrupted Data") — or, when booted from removable storage, next to the content (see Running from a USB stick or an MX4SIO SD adapter), the only configuration with room for the level cache.

PlayStation 3

A 3.2 GHz Cell PPE with 256 MB of XDR main memory and an RSX (NVIDIA NV47) with 256 MB of GDDR3. The port renders through the RSX backend ("Sources/nCine/Graphics/RHI/RSX"), presented by the Ps3 window backend at whatever mode the display accepts.

The RSX is fully programmable, so unlike the fixed-function PVR/GX/GU/GS tier it runs the whole bloom / lighting / combine / rescale chain. There is no shader compiler on the console, so the Cg is compiled to NV40 microcode offline and embedded in the executable.

Toolchain

  • ps3toolchain provides the powerpc64-ps3-elf compilers. Use the prebuilt ps3dev-linux-X64.tar.gz from its nightly releases — building from source takes hours.
  • PSL1GHT is the SDK (librsx, libgcm_sys, libio, libaudio, libsysutil) plus the host tools used for packaging (fself, make_self_npdrm, sfo, pkg, sprxlinker, cgcomp). Built from source by step 8 of ps3toolchain.
  • NVIDIA's Cg Toolkit is needed only to regenerate the shader table (cgcomp wraps libCg.so), not to build the game. See Shaders are compiled offline.
export PS3DEV=<prefix>          # e.g. ~/sdk/ps3dev
export PSL1GHT=$PS3DEV/psl1ght
export PATH=$PS3DEV/bin:$PS3DEV/ppu/bin:$PS3DEV/spu/bin:$PATH

# Prebuilt compilers
curl -L -o ps3dev.tar.gz https://github.com/ps3dev/ps3toolchain/releases/download/<nightly>/ps3dev-linux-X64.tar.gz
tar xzf ps3dev.tar.gz -C $(dirname $PS3DEV)

# PSL1GHT and the host tools (step 8), then the portlibs (step 9)
git clone --depth 1 https://github.com/ps3dev/ps3toolchain
cd ps3toolchain && ./toolchain.sh 8 9

Building

cmake -S . -B build/ps3 -DCMAKE_TOOLCHAIN_FILE=$PWD/cmake/toolchains/ps3dev.cmake \
    -DCMAKE_BUILD_TYPE=Release \
    -DNCINE_CONTENT_DIR=<path to the console content tree>
cmake --build build/ps3 -j$(nproc)

PSL1GHT ships no CMake support, so the toolchain file "cmake/toolchains/ps3dev.cmake" is the project's own, not the SDK's. It defines PLATFORM_PS3, which pins NCINE_PREFERRED_RHI to RSX.

The build produces jazz2.elf and stages a package tree from a stripped copy:

  • sprxlinker rewrites the PRX import stubs, make_self_npdrm wraps the result as EBOOT.BIN
  • fself produces an unsigned jazz2.self that RPCS3 and CFW consoles run straight from disk
  • sfo writes PARAM.SFO with the title and application id (JAZZ20000)
  • the content tree is copied to USRDIR/Content, with Source.pak renamed to Prebaked.pak
  • pkg wraps the whole tree into jazz2.pkg

The application id is derived from the application name, zero-padded to nine characters and uppercased, like the PS Vita title id (see PlayStation Vita). The content id, PARAM.SFO and the runtime writable path all follow from it. Override it with -DPS3_APPID=<id> — anything other than four letters followed by five digits fails configuration.

Shaders are compiled offline

The microcode is generated ahead of time and committed, like the other generated shader headers:

PS3DEV=<prefix> LD_LIBRARY_PATH=<Cg toolkit>/usr/lib64 \
    ./build/Utilities/ShaderCompiler/ShaderCompiler --generate-all

This is the --emit-rsx mode of ShaderCompiler, run by --generate-all when cgcomp is found (through $PS3DEV/bin, PATH, or --cgcomp). It emits Cg from each shader's plain view, not the Vita's LOW_POWER_GPU one (see Compiling that Cg for the PlayStation 3), caps BATCH_SIZE to fit the RSX's constant registers, and compiles with the vp40/fp40 profiles. cgcomp needs the Cg Toolkit on the library path, hence LD_LIBRARY_PATH.

  • Without cgcomp, --generate-all reports "skipped: RsxGeneratedShaders.h" and leaves the committed header untouched. Commit the result — the console build never runs cgcomp.
  • A stage the profiles reject is left out of the table. The backend then fails that program at load time with a message naming the variant. See Limits and known issues for which ones.

Deploying and running

Install jazz2.pkg on a console with custom firmware, or run the staged tree directly:

rpcs3 --no-gui build/ps3/pkg/USRDIR/EBOOT.BIN

RPCS3 needs the PS3 firmware installed once (File → Install Firmware, or --installfw with Sony's PS3UPDAT.PUP), otherwise it stops at "Missing Firmware". Booting EBOOT.BIN in place makes /app_home resolve to USRDIR, so no install step is needed.

Limits and known issues

Threads

  • No threads. PSL1GHT's <pthread.h> declares symbols nothing implements, so pthread_create does not link. Supporting lv2 PPU threads (sysThreadCreate, sys/mutex.h, sys/cond.h) would need a new backend in "Thread.cpp". Multiplayer (including local splitscreen) is compiled out and asset loading is synchronous.

Rendering

  • Three rescale filters have no microcode (they exceed fp40 limits): ResizeCleanEdge, ResizeSabr and ResizeMonochrome. RHI_CAP_HEAVY_RESCALE_SHADERS is left undefined, so they are dropped from Options > Graphics > Rescale Mode. A value saved by another backend falls back to pixel-perfect.
  • Sprite batching is off (RHI_CAP_BATCHING undefined), so every sprite is drawn individually and batched programs are not linked: RPCS3 aborts the batched vertex programs (Src check failed. Aborting) and renders nothing (real hardware untested). Patching the emitted microcode breaks constant fetches — don't.
  • When re-enabled, the batch size is 32, and three places must agree: ShaderCompiler's RsxMaxBatchSize, RsxDevice::MaxBatchSize and IRhiCapabilities::IntValues::MaxBatchSize. Left to derive it, the engine picks 65 and overruns. The backend reports this at load time.
  • Generated stage attributes are struct-qualified (_input.aQuadCorner, not aQuadCorner), while rsxVertexProgramGetAttrib() matches whole names only, so RsxDevice::FindVertexAttribute() matches the name as a suffix. Looking up the bare name finds nothing and renders an all-black frame with no error.
  • Otherwise nothing is known to be missing: under RPCS3 the game runs at 60 FPS with everything rendering correctly and no FIFO desync.

PlayStation Vita

A shader platform with a PowerVR SGX543MP4+ driven by sceGxm. Window and input come from SDL2. It is the only console with a choice of two hardware backends.

NCINE_PREFERRED_RHIWhat it drives
GXM (default)sceGxm directly. Full pipeline (bloom / lighting / combine), without the OpenGL translation layer
OpenGLvitaGL, OpenGL|ES 2.0 on top of sceGxm. Forces the OpenGL|ES path and the strict ES 2.0 profile
SoftwareThe CPU rasterizer, for comparison and bring-up

Toolchain

Install VitaSDK with vdpm (see vitasdk.org), export VITASDK and use "$VITASDK/share/vita.toolchain.cmake".

Building

export VITASDK=/usr/local/vitasdk
cmake -B ./build/vita/ -D CMAKE_BUILD_TYPE=Release \
    -D CMAKE_TOOLCHAIN_FILE=$VITASDK/share/vita.toolchain.cmake
make -j $(nproc) -C ./build/vita/

This builds the GXM backend. Add "-D NCINE_PREFERRED_RHI=OpenGL" for vitaGL. Either way the console needs "libshacccg.suprx", see The console needs a firmware module. The result is "build/vita/jazz2.vpk".

Deploying and running

Install the VPK with VitaShell (or over FTP). It carries the "Content" directory, unpacked into the read-only "ux0:/app/jazz20000/" (mounted as "app0:"), so nothing else is needed to start.

The Vita converts the original game data itself on first run: copy an original installation to "ux0:/data/jazz2/Source/" and it builds "ux0:/data/jazz2/Cache/" — or prepare the tree with AssetPacker to skip the wait. Reinstalling the VPK leaves the cache, source data and settings on "ux0:" alone.

The console needs a firmware module

The VitaSDK has no offline shader compiler, so shaders are compiled on the console by "libshacccg.suprx" from the firmware, whichever backend is used. Extract it following VitaShaRK's instructions and place it in "ur0:/data/".

  • GXM ships Cg source (generated "CgGeneratedShaders.h", see The Cg dialect (PS Vita and PlayStation 3)) and compiles it through vitaShaRK when a program links. Without the module the backend refuses to start and says so in the log.
  • OpenGL passes GLSL to glCompileShader(), which vitaGL compiles through the same SceShaccCg — so external ".shader" files and rescale filters work here too.

The compiled shaders are cached, and shipped

On-console compilation costs about 3.3 s of a cold start, so nCine::RHI::GXM::GxmShaderCache keeps the GXP binaries SceShaccCg produces.

  • Entries are keyed by a 64-bit hash of the exact Cg source, so only changed stages recompile. The file header holds a format revision and a fingerprint of "libshacccg.suprx". Either mismatch rejects the whole pack and the console recompiles.
  • Two packs are loaded: the read-only "app0:/Content/Shaders/ShadersGxm.bin" shipped in the VPK, then the writable one under "ux0:/data/jazz2/Cache/Shaders/" over it. Writes only go to the writable one.
  • To refresh the shipped pack, run once on a console, pull the written pack back and commit it to Sources/Shaders/Prebaked/Vita/ShadersGxm.bin (packaged for Vita only). Commit it exactly as the console wrote it — some keys belong to sources not in "CgGeneratedShaders.h" (runtime-patched batched shaders, the clear/present shaders in "GxmDevice.cpp"), and pruning deletes them. See its README.md.
  • The pack holds 65 binaries: 53 load at startup, the other 12 are the x-ray and blur-behind stages compiled only when a level uses them (see Jazz2::ContentResolver::CompileLayerEffectShaders()). The refresh run must therefore play such a level — the LayerFX test level in Sources/Jazz2/Tests does.

Sprite batching

The backend publishes IRhiCapabilities::IntValues::MaxBatchSize as 32, bounding both the BATCH_SIZE baked into the batched Cg programs and nCine::RenderBatcher. Only this ceiling must match the shader. minBatchSize stays 2, since raising it to the ceiling would draw every shorter run one command at a time.

Limits and known issues

Rendering

  • The ES 2.0 profile has no UBOs and no gl_VertexID, so its shaders use the ESSL 100 lowering from ShaderCompiler (see Platform notes). GXM also lacks a vertex-ID input and reuses the same rewrite, reading the quad corner from a vertex attribute.
  • sceGxm's polygon mode must match the primitive: under the default SCE_GXM_POLYGON_MODE_TRIANGLE_FILL, SCE_GXM_PRIMITIVE_LINES draws nothing. GxmDevice::DrawCommon() selects LINE, POINT or TRIANGLE_FILL from the primitive. Since it is sticky state, the paths bypassing it (stencil band, Clear(), present blit) set TRIANGLE_FILL themselves.
  • Consecutive scenes are not ordered on the GPU, so a scene can sample a render target an earlier scene has not finished (a flickering player light). GxmDevice::FinishScene() waits for those scenes before submitting. Scene dependency flags or a shared sync object don't replace this wait.
  • Buffers are never orphaned: they are GPU-visible memory written in place (nCine::RHI::GXM::GxmBufferObject) and re-declared by nCine::RenderBuffersManager::Remap() while scenes may still read them, so only a fresh block may be cleared.
  • Under Vita3K, GXM shows a one-pixel seam where a repeating texture wraps. It is an emulator artifact, no workaround is applied.
  • Rendering Resolution (Options > Graphics): GXM renders the whole frame into a smaller surface that nCine::RHI::GXM::GxmDevice::PresentFrame() stretches onto the 960x544 panel. Choices are 50% (480x272, default, see nCine::RHI::GXM::GxmDevice::ScreenWidth), 60% (576x326) and 75% (720x408), resized live via nCine::RHI::GXM::GxmDevice::ResizeScreenSurface(). On other shader-tier platforms the option scales the 720x405 view bound instead. Direct-tier consoles don't offer it.
  • Blur effects and high-quality water are on by default, using the cheaper LOW_POWER_GPU shader paths (see Variants, conditionals and includes).
  • Shorter blur chain, since each pass is a separate scene that must finish first: below 100% the first blur pass reads the view directly. At 25% and below the quarter-size level is dropped too (Jazz2::Rendering::PlayerViewport::Initialize(), all platforms).
  • X-ray and blur-behind layers cost about 4–6 ms where several are on screen, mostly from extra scenes.
  • The firmware's Cg compiler is stricter than Vita3K's (e.g. ambiguous call to 'lerp', see The Cg dialect (PS Vita and PlayStation 3)), and one failed program reverts every special layer to its reduced form (see Jazz2::ContentResolver::CompileLayerEffectShaders()). Compile a new shader on a console once before trusting it — refreshing the shipped pack does this.

Audio and threads

  • Sound needs the SDK to provide OpenAL. Without it, audio is compiled out.
  • Module music is libopenmpt, built from source at configure time. NCINE_WITH_XMP=ON uses the SDK's prebuilt libxmp instead (no download, several MB smaller), at the cost of the four .mo3 tracks and some playback accuracy.
  • Asynchronous tracing is disabled, but threads are available.

Networking

  • Online multiplayer works, over ENet only. WITH_WEBSOCKET is forced off (VitaSDK lacks "netinet/ip.h", which IXWebSocket includes). ENET_IPV6=0 selects ENet's IPv4 arm, as on the PSP and Switch — "psp2/net/net.h" has no IPv6. ENet's unused "sys/ioctl.h" include is skipped on this target.
  • VitaSDK's "inet_pton()" is not POSIX: it returns -1 instead of 0 for a host name. This broke HTTPS (libcurl/OpenSSL failed every request with

    "no alternative certificate subject
       name matches target ipv4 address" 

    ) and ENet's "enet_address_set_host_ip()". It is replaced in "Sources/nCine/Backends/Vita/VitaLibcCompat.cpp".

  • "sceNetSendmsg()" caps the number of iovecs well below the 65 ENet may use per datagram. A 33-buffer send returns EMSGSIZE (SCE error 0x28) and ENet drops the connection ("enet_host_service() returned -1", shortly after joining). The Vita uses the gather-then- "sendto()" arm like the 3DS and PSP. Failed sends, receives and socket options log errno and "*sceNetErrnoLoc()".
  • No explicit network bring-up is needed: newlib calls "_vita_net_init()" lazily. Its pool is small (about 140 KB vs. ENet's 256 KB socket buffers) — suspect it first if the transport ever runs out of buffers.

Nintendo Switch

A shader platform built with devkitA64, using SDL2 and desktop OpenGL. Install the switch-dev group and use "$DEVKITPRO/cmake/Switch.cmake":

sudo dkp-pacman -S --needed switch-dev
cmake -B ./build/switch/ -D CMAKE_BUILD_TYPE=Release \
    -D CMAKE_TOOLCHAIN_FILE=${DEVKITPRO}/cmake/Switch.cmake \
    -D DEATH_TRACE_ASYNC=OFF
make -j $(nproc) -C ./build/switch/

DEATH_TRACE_ASYNC must be off — it crashes on startup here. The build produces "build/switch/jazz2.nro" with the game content embedded in its RomFS: copy the .nro to "sd:/switch/" and start it from hbmenu. Like the Vita, the Switch converts the original game data itself — put an original installation into "sdmc:/Games/Jazz2/Source/". The cache and save data appear in "sdmc:/Games/Jazz2/".


Libretro core

Not a console target itself, but a way to reach console-like devices: with NCINE_BUILD_LIBRETRO=ON the game builds as a libretro core ("jazz2_libretro.so", sources in "Sources/nCine/Backends/Libretro") driven by RetroArch, with no window backend of its own. NCINE_PREFERRED_RHI can be:

  • Software — the framebuffer is handed to retro_video_refresh, so it works on every frontend
  • OpenGL — renders into the frontend's FBO via SET_HW_RENDER, targeting OpenGL|ES 3.0
cmake -B ./build/libretro/ -D CMAKE_BUILD_TYPE=Release \
    -D NCINE_BUILD_LIBRETRO=ON -D NCINE_PREFERRED_RHI=Software
make -j $(nproc) -C ./build/libretro/

Continuous integration

Each console is built on every push by its own workflow in ".github/workflows", inside the SDK's container image, and uploads a ready-to-deploy package:

WorkflowContainer imageArtifact
dreamcast.ymlpcercuei/dreamcast-toolchain (compilers only, while KOS, kos-ports and mkdcdisc are built in the job and cached)Jazz2.cdi + Jazz2.elf
wii.ymldevkitpro/devkitppcthe sd/ card tree with apps/Jazz2/boot.dol
gamecube.ymldevkitpro/devkitppc (AssetPacker built in the job for the disc image)Jazz2.iso + the sd/ card tree with Jazz2/Jazz2.dol
3ds.ymldevkitpro/devkitarm (installs 3ds-zlib, 3ds-curl, 3ds-mbedtls)the sdmc/ card tree with 3ds/Jazz2/Jazz2.3dsx
psp.ymlpspdev/pspdevthe ms0/ memory-stick tree with EBOOT.PBP
ps2.ymlps2dev/ps2devJazz2.iso + Jazz2.elf (for PCSX2's -elf)
vita.ymlvitasdk/vitasdkJazz2.vpk
switch.ymldevkitpro/devkita64Jazz2.nro
  • The PlayStation 3 has no workflow — there is no official SDK container. See Toolchain for the manual setup.
  • KallistiOS, kos-ports and mkdcdisc in dreamcast.yml are pinned to specific commits and cached against them, so upstream changes cannot break the build or the runtime.
  • The workflows use the repository's own "Content" (they cannot ship original game data), so their artifacts boot to the main menu only. Prepare a content tree as in Preparing the game content to play a level.

Troubleshooting

  • The game starts, but no episode can be played. The content tree is missing, incomplete or not marked as prepared. Most likely: the tree was never passed as NCINE_CONTENT_DIR (a cached variable — passing it to an already configured build directory does nothing), the tree has "Source.pak" instead of "Prebaked.pak" (a desktop profile conversion), or it is not named "Content" on the medium. See Preparing the game content.
  • The menu itself is unreadable or empty. The conversion didn't get the game's own content (fonts, UI graphics, "Metadata", translations) and warned "No game content directory was found beside the original files". Pass "--content=<dir>" pointing at the repository's "Content", see step 2 of Preparing the game content.
  • No "Source.pak" in …, the disc image will not be marked as prebaked at configure time (PS2, N64) is expected with the console profile, which already names it "Prebaked.pak", see Preparing the content tree. Only a problem if neither package is in the tree.
  • A file removed from the content tree is still on the disc (Dreamcast, PS2). The staging directory is never cleared: delete "<build dir>/cd/" and rebuild, see Building.
  • The intro cinematic crawls on the Dreamcast. The tree was built with --target=console instead of --target=dreamcast, see Preparing the content tree.
  • Text is missing, tilesets look wrong, or a level refuses to load. Usually a stale content tree — regenerate it with an AssetPacker built from current sources. On Wii/GameCube make sure the SD card (or emulator image) was really rewritten.
  • No CDI image after a Dreamcast build. mkdcdisc was not on PATH when CMake configured, see Building.
  • An empty log. Enable the console's receiver — Flycast's serial console, a USB Gecko in slot B on the PowerPC consoles, PPSSPP's stdout. On the Dreamcast and PSP startup messages go to the screen, not the log.
  • std::bad_alloc, an sbrk message, or an unexplained CPU exception on the Dreamcast or GameCube means main memory ran out, while Out of PVR memory allocating … on the Dreamcast is video memory, see Limits and known issues.
  • PPSSPP runs an old build. It boots from its own configured memory stick, see Deploying and running.
  • CMake cannot find the compiler on the Dreamcast. "environ.sh" was not sourced in that shell, see Toolchain.
  • A fully loaded sound is cut short on the Dreamcast. An AICA channel addresses at most 65534 samples, see Limits and known issues.
  • Sound effects are noise on the Wii or GameCube. Samples were emitted little-endian, but buffer formats are native-endian, see Audio backends.
  • "Dead FIFO commands queue state" in RPCS3. Usually the emulator (headless run, no GPU, swapping), see Deploying and running. If genuine, memory the GPU is still reading was reused or the command ring wrapped without a flush.
  • A shader reports "has no compiled RSX microcode" on the PS3. The vp40/fp40 profiles rejected that variant when the table was generated, see Limits and known issues.
  • ppu-gcc refuses to run with "environment variable 'PSL1GHT' not defined". Export it in the build shell, see Toolchain.
  • The PS3 build does not link, with DeflateStream unresolved. The portlibs (zlib) were not built, see Toolchain.