azure

WIP decompilation of Azure Dreams

• azure
  • Setup
    • Submodules
    • CD image
    • PSY-Q
    • The compiler
    • Toolchain
      • Ubuntu
      • Fedora
    • Python
  • Build
  • Decompiling

Setup

Submodules

Several submodules are embedded into the project for tooling. In order to fetch them, run:

$ git submodule init
$ git submodule update --recursive

CD image

Copy the CD image to project directory and name it az.bin. It must have the following SHA256:

2d6843c42ca595687b3780e20ab8c8873705ccead5c8bbc0b69d1fa70bc00a90

PSY-Q

The game was built using PSY-Q 4.1's cc1psx although its runtime libraries are from PSY-Q 4.0.

The build does not run those binaries. The compiler is built from source instead -- see The compiler below -- so what psyq/ is needed for is its headers (include/, which the build compiles against) and its libraries (lib/, which the azure libmatch and azure libscan analysis tools read). The .exes are not used by anything; they are kept as the provenance reference the native compiler was verified against, and tools/validate-psyq.py records their hashes.

Ensure you have a psyq/ directory in the project root with the following contents:

include/
aspsx-2.67.exe
aspsx.exe
cc1plpsx.exe
cc1psx.exe
ccpsx.exe
cpppsx.exe
lib/
    2mbyte.obj
    8mbyte.obj
    autopad.obj
    libapi.lib
    libc2.lib
    libcard.lib
    libcd.lib
    libc.lib
    libcomb.lib
    libds.lib
    libetc.lib
    libgpu.lib
    libgs.lib
    libgte.lib
    libgun.lib
    libmath.lib
    libmcrd.lib
    libpress.lib
    libsio.lib
    libsnd.lib
    libsn.lib
    libspu.lib
    libtap.lib
    noheap.obj
    none3.obj
    poweron.obj

The project includes a script to ensure that this directory has the correct contents:

$ python tools/validate-psyq.py
OK

The compiler

The game's compiler is PSY-Q 4.1's cc1psx, which is SN Systems' build of a Cygnus GCC 2.7.2 snapshot. It is built from source, natively, out of the vendor/old-gcc submodule:

$ git submodule update --init vendor/old-gcc
$ make cdk-gcc

That runs the submodule's gcc-2.7.2-cdk Dockerfile and installs cc1, cpp and gcc into scratch/cdk-gcc/. It needs docker and takes about 20 seconds. make builds it on demand, so this step is optional.

The result is the same compiler the game was built with, not a substitute: its cc1 reports the identical version string (cygnus-2.7.2-970404 SN32.3.7.0004), and every unit in csrc/ compiles to byte-identical assembly against psyq/cc1psx.exe run under wine. A stock FSF GCC cannot be used -- upstream 2.7.2 has no MIPS split-address support and so cannot emit the shape most of the game's global accesses use. See docs/compiler-version.md.

Toolchain

GNU binutils handle assembly and linking. Some Linux distributions have packages for this; otherwise, you may have to build it from source yourself.

Ubuntu

$ apt-get -y update
$ apt-get -y install \
    build-essential \
    g++-mipsel-linux-gnu \
    cpp-mipsel-linux-gnu \
    binutils-mipsel-linux-gnu

Fedora

$ dnf -y install gcc-mips64-linux-gnu

Python

Make sure you have Python and uv installed.

Build

$ make extract # Extract files from CD image
$ make splat   # Extract code/data from files
$ make         # Build PSX EXE files from extracted data

Decompiling

docs/where-we-are.md is the entry point: state, workflow, tools and queue. docs/matching-levers.md is how this compiler behaves -- read it before writing a function, and add to it when you learn something.