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.
| Console | Toolchain (CMake toolchain file) | Rendering backend | Window backend | Build artifact |
|---|---|---|---|---|
| Nintendo 64 | libdragon (cmake/toolchains/n64.cmake) | RDP — fixed-function | N64 | jazz2.z64 (bootable ROM) |
| Sega Dreamcast | KallistiOS (kallistios.toolchain.cmake) | PVR — fixed-function | Dc | jazz2.cdi (bootable disc image) |
| Nintendo Wii | devkitPPC + libogc (Wii.cmake) | GX — fixed-function | Ogc | boot.dol (in a staged sd/ tree) |
| Nintendo Wii U | devkitPPC + wut (WiiU.cmake) | GX2 (native, shaders) | SDL2 | jazz2.wuhb (Wii U Homebrew Bundle) |
| Nintendo GameCube | devkitPPC + libogc (GameCube.cmake) | GX — fixed-function | Ogc | jazz2.iso (bootable disc image) and Jazz2.dol (in a staged sd/ tree) |
| Nintendo 3DS | devkitARM + libctru + citro3d (3DS.cmake) | PICA — fixed-function | Ctr | Jazz2.3dsx (in a staged sdmc/ tree) |
| PlayStation Portable | pspdev (pspdev.cmake) | GU — fixed-function | Psp | EBOOT.PBP (in a staged ms0/ tree) |
| PlayStation 2 | ps2dev (ps2dev.cmake) | GS — fixed-function | Ps2 | jazz2.iso (bootable disc image) |
| PlayStation 3 | ps3toolchain + PSL1GHT (cmake/toolchains/ps3dev.cmake) | RSX (native libgcm, shaders) | Ps3 | jazz2.pkg (and an unsigned jazz2.self) |
| PlayStation Vita | VitaSDK (vita.toolchain.cmake) | GXM (native sceGxm, default), OpenGL via vitaGL (ES 2.0 profile) or Software | SDL2 | jazz2.vpk |
| Nintendo Switch | devkitA64 (Switch.cmake) | OpenGL | SDL2 | jazz2.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_CACHEin"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,GSandPICAimplement each effect as fixed-function passes transpiled by ShaderCompiler from the same.shaderfiles — 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= | For | Cinematics |
|---|---|---|
console | Every console except the Dreamcast and the GameCube (wii and psp are aliases) | Original .j2v files copied unchanged |
dreamcast | Sega Dreamcast | Re-encoded into Jazz2:: |
gamecube | Nintendo GameCube | Re-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:
| Console | Content directory | Cache / 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
Cacheand 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_DIRis copied into itsContentsubdirectory 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.
| Feature | N64 | Dreamcast | Wii | GameCube | Wii U | 3DS | PSP | PS2 | PS3 | Vita | Switch |
|---|---|---|---|---|---|---|---|---|---|---|---|
Threads (NCINE_WITH_THREADS) | No | Yes | Yes | Yes | Yes (newlib pthreads) | Yes (pthread shim over libctru) | Yes | No | No | Yes | Yes |
Asynchronous tracing (DEATH_TRACE_ASYNC) | No | No | No | No | No | No | No | No | No | No | No |
| Audio backend | N64 (RSP mixer) | AICA | ASND | ASND | SDL (software mixer, AX voices through wiiu-sdl2) | NDSP | PSP | PS2 | PS3 | OpenAL if the SDK has one | OpenAL if the SDK has one |
| Sound effects | Yes | Yes | Yes | Yes | Yes | Yes (needs DSP firmware, see Limits and known issues) | Yes | Yes | Yes | SDK-dependent | SDK-dependent |
| Module music | Yes (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 filter | No | No | No | No | No | No | No | No | No | SDK-dependent | Yes |
| Local splitscreen | No — needs threads | Yes | Yes | Yes | Yes | Yes (one controller) | Yes (one controller) | No — needs threads | No — needs threads | Yes | Yes |
| Online multiplayer | No | No | No | No | No (not enabled yet, see Limits and known issues) | Yes (ENet only, see Limits and known issues) | Yes (ENet only, see Limits and known issues) | No | No | Yes (ENet only, see Limits and known issues) | Yes |
| Post-processing and rescale filters | No | No | No | No | Yes | No | No | No | Yes | Yes | Yes |
X-ray and blur-behind tile layers (TILEMAP_LAYER_EFFECTS) | No — reduced at load | No — reduced at load | No — reduced at load | No — reduced at load | Yes | No — reduced at load | No — reduced at load | No — reduced at load | Yes (microcode generated, not yet run on a console) | Yes | Yes |
External .shader files | No | No | No | No | No (shaders are compiled offline) | No | No | No | No (no runtime compiler) | Yes | Yes |
| Converts the game data itself | No | No | Yes | No | Yes | Yes | Yes | No | Yes | Yes | Yes |
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::"nCine/Audio/Backends/<backend>/".
| Backend | WITH_* | What it drives |
|---|---|---|
| AL | WITH_OPENAL | System OpenAL on desktop, the SDK's own on the Switch and Vita |
| ASND | WITH_ASND | libogc's DSP mixer (Wii and GameCube, ships with devkitPPC) |
| AICA | WITH_AICA | The Dreamcast sound processor through KallistiOS: wavetable channels for effects, snd_stream for music |
| PS3 | WITH_PS3AUDIO | PSL1GHT's libaudio (lv2 offers only an output ring, so this backend is a software mixer on the PPE) |
| PSP | WITH_PSPAUDIO | Integer software mixer into one sceAudio channel, on its own thread |
| NDSP | WITH_NDSP | Same 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 |
| N64 | WITH_N64AUDIO | libdragon'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) |
| PS2 | WITH_PS2AUDIO | Software mixer into the audsrv IRX stream, topped up per frame (no threads). The SPU2 resamples in hardware |
| SDL | WITH_SDLAUDIO | Software 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::
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.
| Console | Where the trace goes |
|---|---|
| Nintendo 64 | stderr 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 |
| Dreamcast | dbgio: the framebuffer console during startup, then the SCIF serial port. Emulators print it to their log, dc-tool to its console |
| Wii / GameCube | A 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 U | OSReport(): 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 3DS | svcOutputDebugString: 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 Portable | stdout via sceIoWrite on fd 1: PPSSPP log, psplink console, plus the debug screen until the GU takes over |
| PlayStation 2 | The 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 3 | sysTtyWrite: fd 1 and 2 go to the console TTY on hardware and to RPCS3's log |
| PlayStation Vita | sceClibPrintf, read with host tools (psp2shell, VitaCompanion) |
| Switch | svcOutputDebugString, 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::
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 noglDrawElementsBaseVertex()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 viaResolveHostIndices()and avertexAt()resolver, and quad recognition (one GE rectangle,GX_QUADSquad 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_tslot per cell into a dense array of only the cells that have an event (EventMapEventLayout). Empty cells read as a shared empty tile. Writes go throughEdit(), which allocates the cell, whileFind()looks up without allocating. A reference fromEdit()is valid only until the nextEdit(). - 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 throughSet(). 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), andCombineRenderer::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 plusGX,PICA,GSandGU. The N64 has its own cache in the RDP tile format.PVRand 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:
| Console | Replaced | Why |
|---|---|---|
| Dreamcast | pow, log, ceilf | The SH-4 ABI defaults to single precision, so every double operation switches FPU mode |
| Nintendo 64 | floorf, ceilf | The VR4300 has no rounding instruction |
| PlayStation 2 | pow, log, double division, floorf, ceilf | Single-precision FPU only, and music decodes on the main thread |
| PSP | pow, log, double division, floorf, ceilf | Single-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 least7c57c409("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
audioconv64is required.videoconv64plus 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
consoletree 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) andmkdfs(DragonFS image of the content), concatenated byn64tool.ed64romconfigsets 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 withstrtod()(string streams pull in ~350 KB of<locale>), the port defines its ownstd::terminatehandler ("nCine/MainApplication.cpp", avoids linking the demangler), and the game target is built without RTTI on every platform, since casts useruntime_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::TilePaddingborder (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=n64tree 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-
NDEBUGlibdragon enables overflow, divide-by-zero and invalid-operation traps, but the game assumes IEEE behaviour (e.g.FLT_MAXsquared), soFCR31enable 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, andVI_AA_MODE_NONEhits 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 asPrimitiveType::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, seeTileMap::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::ShadowsEnabledis 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.
- The hot code is linked in a fixed order made from a profile (
- 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
.j2bmodules 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 adesktopcache 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. KeepMusic: 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_DIRis 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-elfGCC 15.2 abort),Releaseuses-O2, andDEATH_USE_FAST_MATHis 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-toolover 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 …, thenstd::bad_allocand an abort (the emulator reports only a CPU exception). Video memory reportsOut 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=OFFbrings libopenmpt back (both are compiled from source). libxmp cannot read the four.mo3tracks. - 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_streamhandle (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(), readsCONF_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
.shaderfiles. - 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.mo3tracks.-D NCINE_WITH_XMP=OFFswitches 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 (theshared_ptrreference count overflow test, for example). The game then hangs with a grey screen at the first one. Replacing the conditional traps in"jazz2.elf"withnopand runningelf2rplandwuhbtoolagain 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_MULTIPLAYERis 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::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()):
Contentnext to the executable (when a loader started it from SD).- The disc, if it is this game's and the drive is ready — so disc content wins over a stale tree on a card.
Jazz2/Contenton each SD card:sd:(SD2SP2), thencarda:andcardb:(SD Gecko).- 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.gcifiles 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
wiiuseandbtefor 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
libsysbaseover libctru'sLightLock/CondVar, sofind_package(Threads)succeeds andNCINE_WITH_THREADSstays 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::
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.3dsxsends 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.3dsxdirectory. Networking needs no setup,soc:uruns 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=1gives 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 = 0reads the last row in memory), soPicaTexture::BuildPage()stores the source's first row last. Render targets need no extra flip:PicaDevice::ApplyDrawTarget()sends a pass's first raster row tov = 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, soPicaDevice::Clear()callsC3D_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
swkbdapplet, 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) havegetaddrinfo()andpoll(). The vendoredenet.honly routessendmsg()andrecvmsg()throughsendto()(buffers gathered into one datagram) andrecvfrom().ENET_IPV6=0(noin6_addrin libctru) andWITH_WEBSOCKETis off (no"netinet/ip.h").CtrPlatform::Initialize()lends the service a page-aligned 1 MB buffer withsocInit()before any socket opens, andShutdown()takes it back. The WLAN is the system's business: an offline console simply fails to connect. In Azahar a server on127.0.0.1is the host. - A failed socket call is not treated as a lost connection. The one
soc:ubuffer is shared by every socket and HTTPS request, so transient errors happen on hardware (not in Azahar). The 3DS arms ofenet_socket_send()andenet_socket_receive()treat every error exceptEBADF,ENOTSOCKandEFAULTas nothing sent/received. ENet resends reliable data and the peer timeout still catches a dead server. The first 16 errors are logged with theirerrno. - 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", whereApplyPlatformWebRequestOptions()points libcurl (as on the PSP and Vita). Without it the update check and server list fail with an mbedTLS-0x3E00error naming the default path. The console clock is real time (unlike pspdev's, see Limits and known issues). When porting further:WebRequest.cpppicks 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 andC1-2858-3on 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 / AnimDurationdivides 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()inGuDevice::PresentFrame(), soGuDevice::SyncBeforeStoreRelease()kicks the list and waits for the GE beforeGuTexturefrees a store (RefreshGeStore(),FreeGeStores(), the destructor), andEnsureList()opens a fresh one. OtherwisesceGuSync()hangs and the firmware kills the process (same freeze andC1-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-exceptionsa failedoperator newis a bareabort(). Thestd::set_new_handlerfrom 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_TEXTURESthey 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).
sceGudoes not bounds-check it, soGuDevice::PresentFrame()warns once if a frame passes three quarters. - Threads are on, over pspdev's pthread-embedded.
pthread_setname_npand CPU affinity are compiled out, as on the libogc consoles.pthread_tis a pointer (usereinterpret_cast), and stack information comes fromsceKernelReferThreadStatus(). - Thread stacks are 64 KB, and raising them is not free.
sceKernelCreateThreadallocates stacks from what the firmware kept back, which holds one 256 KB stack but not two. The second creation fails withNO_MEMORYand 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_colorpass expands into a modulated draw plus an additive silhouette, and theMODULATE_X2/MODULATE_X4presets 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_OPENMPTis forced off — libopenmpt's first module load takes about 29 seconds on this CPU — andNCINE_WITH_XMPis on by default. libxmp reads the original.j2bmodules directly, but not MO3, so the four.mo3tracks 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 realjal 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-coreneeds custom firmware, reports the core unavailable under Adrenaline (no ME firmware image) and hangs PPSSPP inkinit(). Code touching the ME must first test for the emulator withsceIoDevctl("kemulator:", 0x03, ...), which succeeds only there.
System services
- The C library's clock is replaced. pspdev's libcglue implements
_gettimeofday()(behindtime(),gettimeofday()andstd::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()isgmtime().GetLocalTimeZoneOffset()(DateTime.cpp) gets the offset, daylight saving included, by passing one tick throughsceRtcConvertUtcToLocalTime(), andGetLocalTm()applies it. - HTTPS needs its own CA bundle. The configure step downloads curl.se's
cacert.pemand stages it underContent/, as on the Vita."Sources/Jazz2/PlatformWebRequest.h"pointsCURLOPT_CAINFOat it and clearsCURLOPT_CAPATH, because mbedTLS reads the default directory (/etc/ssl/certs) first and fails on it. To debug a failed verification, routeCURLOPT_DEBUGFUNCTIONinto the trace. - Text is entered through the firmware's on-screen keyboard. nCine::
MainApplication:: ShowScreenKeyboard() opens the modal sceUtilityOSK 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
*libspec already appends-lpsputility -lpsprtc -lpspnet_inet -lpspnet_resolver -lpspsdk -lpspmodinfo -lpspuser. Adding any of them totarget_link_librariessplits their stubs,psp-fixup-importsreports"could not fixup imports, stubs out of order", and syscalls such assceNetInetSocket()end up calling something else.
Networking
- Online multiplayer works, over ENet only.
WITH_WEBSOCKETis forced off (pspdev has neither"netinet/ip.h"nor"poll.h") andENET_IPV6=0(sceNetInethas no IPv6). The vendored"Sources/Dependencies/enet/enet.h"supplies thepoll(),getaddrinfo()andgetnameinfo()libcglue lacks, overselect()andgethostbyname()/gethostbyaddr(). Non-blocking sockets usesetsockopt(SO_NONBLOCK), sincefcntl()does not reach the firmware's sockets, and receiving usesrecvfrom()(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 anENetAddresshost indexes a table of seen MAC addresses, writtenAA:BB:CC:DD:EE:FF. nCine::Backends::PspNetwork::AdhocBegin() drops the access point and brings upsceNetAdhoc/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 byPspNetwork::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 useff02::1multicast plus anAF_INETbroadcast socket (TryCreateLocalBroadcastSocket(), and the multicast one isIPV6_V6ONLYsince 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
Contentdirectory next to the executable, on any device and in any directory, taken fromargv[0](seenCine::Backends::Ps2Storage::SetBootPath()). Games/Jazz2/on a mounted unit, so the tree does not collide with a loader's ownAPPS,DVDandCFG(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:
| Screen | Set when |
|---|---|
| Red | Static initialization begins |
| Green | main() reaches MainApplication::Run() |
| Blue | The trace system is up and the boot console is about to open |
| Black | Never — 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
PSMCT16display 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 (seeJazz2::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_colorpass expands into a modulated draw plus an additive silhouette (via a white-RGB CLUT, seeGsDevice::AcquireCoverageClutForOffset()), and theMODULATE_X2/MODULATE_X4presets 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_OPENMPTis forced off (libopenmpt'sto_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.mo3tracks of the 56.
- 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::
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 theicon.systhe 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-elfcompilers. Use the prebuiltps3dev-linux-X64.tar.gzfrom 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 (
cgcompwrapslibCg.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:
sprxlinkerrewrites the PRX import stubs,make_self_npdrmwraps the result asEBOOT.BINfselfproduces an unsignedjazz2.selfthat RPCS3 and CFW consoles run straight from disksfowritesPARAM.SFOwith the title and application id (JAZZ20000)- the content tree is copied to
USRDIR/Content, withSource.pakrenamed toPrebaked.pak pkgwraps the whole tree intojazz2.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-allreports"skipped: RsxGeneratedShaders.h"and leaves the committed header untouched. Commit the result — the console build never runscgcomp. - 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, sopthread_createdoes 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
fp40limits):ResizeCleanEdge,ResizeSabrandResizeMonochrome.RHI_CAP_HEAVY_RESCALE_SHADERSis 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_BATCHINGundefined), 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::MaxBatchSizeandIRhiCapabilities::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, notaQuadCorner), whilersxVertexProgramGetAttrib()matches whole names only, soRsxDevice::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_RHI | What it drives |
|---|---|
GXM (default) | sceGxm directly. Full pipeline (bloom / lighting / combine), without the OpenGL translation layer |
OpenGL | vitaGL, OpenGL|ES 2.0 on top of sceGxm. Forces the OpenGL|ES path and the strict ES 2.0 profile |
Software | The 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/".
GXMships 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.OpenGLpasses GLSL toglCompileShader(), 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 itsREADME.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/Testsdoes.
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).GXMalso 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_LINESdraws nothing.GxmDevice::DrawCommon()selectsLINE,POINTorTRIANGLE_FILLfrom the primitive. Since it is sticky state, the paths bypassing it (stencil band,Clear(), present blit) setTRIANGLE_FILLthemselves. - 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 bynCine::RenderBuffersManager::Remap()while scenes may still read them, so only a fresh block may be cleared. - Under Vita3K,
GXMshows a one-pixel seam where a repeating texture wraps. It is an emulator artifact, no workaround is applied. - Rendering Resolution (Options > Graphics):
GXMrenders 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_GPUshader 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=ONuses the SDK's prebuilt libxmp instead (no download, several MB smaller), at the cost of the four.mo3tracks and some playback accuracy. - Asynchronous tracing is disabled, but threads are available.
Networking
- Online multiplayer works, over ENet only.
WITH_WEBSOCKETis forced off (VitaSDK lacks"netinet/ip.h", which IXWebSocket includes).ENET_IPV6=0selects 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 returnsEMSGSIZE(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 logerrnoand"*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 toretro_video_refresh, so it works on every frontendOpenGL— renders into the frontend's FBO viaSET_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:
| Workflow | Container image | Artifact |
|---|---|---|
dreamcast.yml | pcercuei/dreamcast-toolchain (compilers only, while KOS, kos-ports and mkdcdisc are built in the job and cached) | Jazz2.cdi + Jazz2.elf |
wii.yml | devkitpro/devkitppc | the sd/ card tree with apps/Jazz2/boot.dol |
gamecube.yml | devkitpro/devkitppc (AssetPacker built in the job for the disc image) | Jazz2.iso + the sd/ card tree with Jazz2/Jazz2.dol |
3ds.yml | devkitpro/devkitarm (installs 3ds-zlib, 3ds-curl, 3ds-mbedtls) | the sdmc/ card tree with 3ds/Jazz2/Jazz2.3dsx |
psp.yml | pspdev/pspdev | the ms0/ memory-stick tree with EBOOT.PBP |
ps2.yml | ps2dev/ps2dev | Jazz2.iso + Jazz2.elf (for PCSX2's -elf) |
vita.yml | vitasdk/vitasdk | Jazz2.vpk |
switch.yml | devkitpro/devkita64 | Jazz2.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.ymlare 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"(adesktopprofile 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 prebakedat configure time (PS2, N64) is expected with theconsoleprofile, 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=consoleinstead 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.
mkdcdiscwas not onPATHwhen 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, ansbrkmessage, or an unexplained CPU exception on the Dreamcast or GameCube means main memory ran out, whileOut 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/fp40profiles rejected that variant when the table was generated, see Limits and known issues. ppu-gccrefuses to run with "environment variable 'PSL1GHT' not defined". Export it in the build shell, see Toolchain.- The PS3 build does not link, with
DeflateStreamunresolved. The portlibs (zlib) were not built, see Toolchain.