This post covers the Official Nintendo 64 Software Development kit that was sent to developers is actually split among a number of different discs due to its size.
These Discs include:
- N64Kit - Applications used for N64 development
- N64 OS - The SDK files (includes, libraries etc)
- Nintendo 64 Sound Tools - Tools for Musicians
- Documentation
N64Kit CD (N64 Developers Toolkit)
The N64 Developers toolkit contained all the following applications used for N64 Development:
- ccbl - Color Combiner and Blender N64 code
- DPTEST - PC application to communicate with ccbl
- DDTools
- HVQ/HVQM - Image and Video compression
- Monegi Multi Viewer64
- NIFF
- NuSYSTEM
- N64 Disk Drive Multi File System (MFS)
The CD contains a PC and SGI folder, with the SGI folder simply containing a tar archive of all the contents.
On Windows a Setup.exe file was included that is installed into C:\nintendo\n64kit and contained pre-compiled executables for all of the main applications.
Development-environment constraints
Zygal Studios discusses the difficulties of the Nintendo 64 development environment. It provides historical context for the official tools and libraries catalogued in this article.
Modern Vintage Gamer examines why Nintendo 64 games were difficult to develop. The overview complements the catalogue of SDK components with the constraints developers faced when using them.
Known Versions of N64Kit
Latest Version: 5.2
Released Versions: 3.0, 4.0, 4.1, 5.0, 5.1, 5.2
The supplied Toolkit 5.2 CD label is dated August 2000 1.
Version 5.1 (10th Feb 2000) of the kit was partially released in the BroadOn archive leak of May 2020 due to its use in the iQue player development.
ccbl - ColorCombiner and Blender Demo
This is an application that runs on the Nintendo 64 hardware to teach programmers about the RDP features. It has the ability to communicate with a Windows Application called dptest for which the source code is also available.
dptest - Display Processor Test tool
Windows application that communicates with the N64 application ccbl to save and load configurations.
It works with a number of different N64 development flash cartridges such as:
- MSP-A/MSP-B/MSP-C
- Partner-N64
- IS-Viewer64
Files in the dptest folder.
HVQ - Image & Video compression
The Hybrid Vector Quantization (HVQ) algorithm is an effective form of image compression for low bit rate images and can out perform JPEG by between 10 and 20%.
This allowed developers to compress their textures down and allow much more data to be stored on the limited cartridge space provided by the Nintendo 64.
Also since videos are just a collection of images there is a variant of the algorithm called HVQM that compress video content. This folder contains code for both the image and video compression tools.
If a game used the HVQ algorithm they were required to show a logo which was contained in the HVQlogo folder.
The source code suggests that the algorithm may have been written by Hudson.
hvq2enc
This folder contains a pre-built Windows executable called hvq2enc.exe for compressing BMP or PPM images into HVQ encoded images.
There is also a version of this tool for video content called hvqm2enc.exewhich supports converting uncompressed AVI files to compressed HVQM2 files.
libhvq2
libHVQ2 is the main static library used to decompress static images (for movies see libhvqm2) on the Nintendo 64. The source code for the library itself is not provided in the SDK, but the header files and the static library files (including RSP microcode) are included along with some pretty decent documentation.
There are two methods of decompressing the data, one is purley CPU using just functions in the static library.
The other uses the CPU to decode half of the data then passes it over to the RSP microcode to do the rest, saving CPU time.
| Filename | Description |
|---|---|
| GUIDE.txt | Tutorial for using both the CPU and RSP versions |
| rspcode/hvq2sp2.o | RSP Microcode to decompress the intermediate image to 32-bit image data |
| rspcode/hvq2sp1.o | RSP Microcode to decompress the intermediate image to 16-bit image data |
| FUNCTIONS.txt | Documentation for each function in the lbirary |
| lib/HVQ2File.h | Contains the HVQ2Header structure for parsing the data header |
| lib/libhvq2.a | The main static library that must be linked to use HVQ functionality |
| lib/HVQmd.h | N64 version of the Machine Dependent (MD) definitions. |
| lib/hvq2dec.h | Header file for all the functions and main structures in the library |
| README.txt | Overview of the folder contents |
nuHvq - Nintendo Ultra HVQ
NuHVQ is a Nintendo 64 sample project provided by Monegi Corporation to demonstrate loading HVQ compressed images on the N64 via the NuSystem API.
This is a higher level version of the code presented in the sample folder, which essentially does the same thing but without NuSystem.
This example seems to have been forked from the nu4 sample code as it includes the same music and code.
sample - Sample code for N64
This folder contains the bare-bones implementation of a N64 image viewer for images compressed with HVQ. This does not use the NuSystem API so it is lower level than the nuHvq sample but provides similar functionality.
| Filename | Description |
|---|---|
| hvqwork.c | Variable setup for memory used by HVQ2 RSP microcode |
| sample.hvq | Sample Image compressed with HVQ |
| Makefile | Standard Makefile for building sample |
| system.c | Implements the standard boilerplate code such as mainproc |
| spec | Standard ROM spec file but notably includes the “sample.hvq” image as a segment |
| cfb.c | Just contains the CFBPix Frame Buffer |
| main.c | Contains the sample specific logic to load the HVQ image |
| README.txt | Brief overview of how to use the sample |
| system.h | Header file for all the definitions from main.c |
| hvqbuf.c | Simply defines the HVQ buffer where the image is read into |
Building ROM images with makerom
Nintendo’s documented development pipeline compiles C and assembly into relocatable objects, then uses makerom to link and pack code and data according to a segment specification. The tool can also add raw files to the cartridge image. A segment’s location in ROM therefore does not by itself tell you where the game will load it in RAM [^1].
The documented IRIX 5.3 compiler setup used these options when building N64 modules:
| Option | Purpose in Nintendo’s documented build |
|---|---|
-non_shared |
Avoid position-independent, shared code |
-G 0 |
Avoid the compiler’s small-data/global-pointer area |
-mips2 |
Target the MIPS II instruction set; recommended by the manual |
These are historical SDK instructions, not universal flags for every retail game. A matching decompilation must establish its target game’s compiler revision, per-file options, linker order, and segment layout from that game’s evidence. Nintendo also distinguishes the release libultra.a from the debug libultra_d.a when packing a retail ROM [^1].
N64 Operating System
The N64 OS was initially released with both SGI and PC versions on the same disc, later it was moved to a disc for each operating system.
On Windows it was installed into C:\Ultra\usr and used a UNIX-like directory structure containing the following folders:
- include - C Source code Header files
- lib - compiled static libraries for N64
- sbin - a few custom command line tools
- src - Source code for Demo applications and the libultra and libnaudio libraries
The src/PR demo projects range from a first triangle to texture filtering, audio scheduling, terrain editing, and hardware performance tests. A dedicated guide to the N64 SDK demos maps the PC 2.0H, IRIX 2.0I, and PC 2.0J/2.0L packages and compares them with the Turok and Oman copies.
Known Versions
Latest Version: 2.0L The dates below come from the versions’ release notes. They may differ from the dates the discs were distributed 2 3:
| Version | Release notes dated |
|---|---|
| 2.0G | 30 September 1996 |
| 2.0H | 24 February 1997 |
| 2.0I | 15 December 1997 |
| 2.0J | 1 February 1999 |
| 2.0K | 4 August 1999 |
| 2.0L | 3 July 2000 |
The inspected OS-PC 2.0H installer’s readme.20h also prints 1997.3.19 2.0H(PC). That PC-specific date is later than the 24 February date on the general 2.0H release notes 4.
References
-
The supplied
Nintendo_64_Developers_Toolkit_v5.2.jpgshows the original CD label readingAugust, 2000. This establishes a month on the disc, not a precise distribution day. ↩ -
Oman
MAN/RELNOTESand Turoksrc/PR/relnotesare byte-identical. They identify Ultra 64 version2.0G for RCP 2.0and are headedSeptember 30 releasewithout a year; n64os-info’s release-note chronology identifies the date as 1996. ↩ -
Supplied OS v2.0L release-note collection,
usr/src/PR/doc/relnotes_old/relnotes20H.txt,relnotes20I.txt,relnotes20J.txt, andrelnotes20K.txt, plususr/src/PR/doc/relnotes20L.txt. The 2.0H and 2.0I notes print month and day without a year; n64os-info’s release-note chronology identifies them as 1997. ↩ -
Supplied Nintendo 64 OS-PC v2.0H,
N64os20h.z, extractedreadme.20h. ↩