# Pikuma PS1

A rest from the usual.

![img](./docs/assets/splash.jpg)

## Dependencies

I will be programming from a Windows 11 machine (may eventually try this on the Steam Deck...):

[armips](https://github.com/Kingcom/armips)

* Supports doing bare-metal assembly for the ps1
* `scoop install armips` or just clone and build..
* Was used early in the course. Now I just use an macro asm dsl in C11.

[luajit-2.1](https://github.com/LuaJIT/LuaJIT.git)

```
scoop install luajit
```

* Used for lua scripts
* Particularly, ps1_meta.lua which is a staged metaprogram pass for the custom C11 Assembly DSL used in this codebase.

[lpeg](https://github.com/roberto-ieru/LPeg.git)

* Lua is slow (even jitted) so this helps.

[lfs (LuaFileSystem)](https://github.com/lunarmodules/luafilesystem)

* Native directory enumeration + `mkdir` for the build scripts.
* Used by `passes/word_count_eval.lua :: scan_dir` (native walk vs. `dir /b /s` subprocess,
  ~2ms vs. ~56ms) and by `duffle.lua :: ensure_dir` + `to_absolute_path` (avoids
  `cmd.exe mkdir` + `cd` shell spawns, ~50ms each).

[pscx-redux](https://github.com/grumpycoders/pcsx-redux/): A collection of tools, research, hardware design, and libraries aiming at development and reverse engineering on the PlayStation 1.

* Used as the runtime sandbox emulated the ps1
* Has hookups to behaving as a gdb server which can be utilized with the gdb client in vscode.
* Supports symbolic info emitted by armips
* pysq library has been sucessfully adjusted for modern compiler usage (see: `src/`)

[MIPS Toolchain (from pscx-redux)](https://static.grumpycoder.net/pixel/mips/)

* Used for building ps1 programs for the C runtime provided by the psyq/o SDK

[nugget](https://github.com/pcsx-redux/nugget)

* Readonly mirror of pcsx-redux's `src/mips` directory.
* Not necessary if the pcsx-redux repo is cloned

[PSX Psy-Q SDK (supplied by `psx.arthus.net`)](https://psx.arthus.net/sdk/Psy-Q/)

* Original official SDK
* Modernized using obj parser to extract info for GNU toolchain usage.
* Can either grab from arthus [psyq-4.7-converted-full.7z](https://psx.arthus.net/sdk/Psy-Q/psyq-4.7-converted-full.7z) or [psyq-4_7-converted-light.zip](psyq-4_7-converted-light.zip)
  * The light version omits the link modules (object files), just keeps the static archives.
* Can be utilized effectively with the includes below

[psyq_include_what_you_use](https://github.com/johnbaumann/psyq_include_what_you_use/)

* Fixes psyq headers to include what they use, so changing the include order in your project doesn't break compiling.
* Needed if you want to link and utilize the psyq C SDK

[Other toolchains (not used here)](https://www.psx.dev/getting-started)

## Gallery

![clear!](./docs/assets/pcsx-redux.main_2025-08-03_18-02-08.png)  
![traingles!](./docs/assets/pcsx-redux.main_2025-08-03_19-28-22.png)  
![polys!](./docs/assets/pcsx-redux.main_2025-08-03_20-45-35.png)  
![hello_psyq!](./docs/assets/pcsx-redux_2025-08-05_23-01-19.png)
![cube!](./docs/assets/pcsx-redux_2025-10-11_03-04-01.png)
![cube and floor!](./docs/assets/pcsx-redux_2026-07-10_22-47-02.png)

Win 11 machine:

![system_info](./docs/assets/system_info.png)

Still haven't gotten around to trying this on linux...
