Largely written with agentic coding. I direct the agents and test their work in two places: PSoXide's emulator, which profiles every cycle, and a real PlayStation, which shows me where the emulator is wrong. Working between them is where the accuracy and the speed come from. How PSoXide is built
Half-Life for the original PlayStation, built in Rust on the PSoXide SDK.
HL-PSX is a bring-your-own-assets port. The build reads maps, models, sprites, sounds, dialogue, music, and UI resources from your own Half-Life installation and converts them into data suitable for the PlayStation. Valve assets and generated disc images are not distributed by this repository.
Important
HL-PSX is a noncommercial, source-only compatibility project. Building it requires a lawfully obtained local Half-Life installation. Generated data and BIN/CUE images are local outputs and must not be redistributed as project releases. See LICENSING.md, PROVENANCE.md, and THIRD_PARTY_NOTICES.md.
HL-PSX is under active development and is tested in both PSoXide and on original PlayStation hardware.
| Area | Current state |
|---|---|
| Content | The campaign and Hazard Course pipeline cooks and audits all 103 runtime maps. |
| Gameplay | GoldSrc-style movement, weapons, damage, scripted entities, doors, trains, NPCs, map transitions, saves, and menus are implemented. |
| Presentation | PlayStation-native world/model rendering, animated models, HUD, sprites, dialogue, sound effects, and CD audio are supported. |
| Target | 320×240 output with a 20 fps simulation target on original hardware. |
| Distribution | Source only. No original or converted Valve assets and no generated disc image are included. |
This is not a finished retail-quality release. Compatibility, visual accuracy, performance, and real-hardware behaviour continue to be improved.
See CHANGELOG.md for recent performance measurements and fixes.
You need:
- A lawfully obtained Half-Life installation from Steam or retail.
- Rust installed through rustup. Use rustup rather than an operating-system Rust package so the repository can select its pinned nightly toolchain automatically.
- Host build tools/linker for Rust executables (Xcode Command Line Tools on macOS, a C/C++ toolchain on Linux, or Visual Studio Build Tools on Windows).
- Internet access for the first build so Cargo can download that toolchain, the Rust dependencies, and the pinned PSoXide sources.
You do not need a separate PSoXide checkout, Make, FFmpeg, Python, or a MIPS binutils install.
Download and extract the source archive, or clone it with Git:
git clone https://github.com/EBonura/hl-psx.git
cd hl-psxIf you downloaded the archive, open a terminal in the extracted hl-psx
folder instead.
Run this one command from the repository root:
cargo hl-build buildcargo hl-build is a Cargo alias defined in this repository's
.cargo/config.toml, so it only works from the repository root. It is short
for cargo run --release --manifest-path host/hl-build/Cargo.toml --.
The builder finds Half-Life automatically in the standard Steam location on
macOS, Linux, and Windows. If it says that Half-Life was not found, provide
either the Half-Life installation folder or its valve folder:
cargo hl-build build --half-life "PATH_TO_HALF_LIFE"Keep the quotation marks when the path contains spaces.
The first build takes longer because it converts the complete campaign and Hazard Course, then compiles the PlayStation executable and packs the disc. When it finishes, the playable image is:
dist/hl-psx.cue
The adjacent dist/hl-psx.bin file is part of the same disc and must remain
beside the CUE file. To rebuild after updating the source, run the same
cargo hl-build build command again.
All converted content stays inside this checkout under data/, build state
and reports stay under .hlpsx/, and the final image stays under dist/.
Nothing is copied elsewhere unless you explicitly use install with
--games-dir.
The disc opens with Half-Life's own startup movie (the one named in your
install's media/StartupVids.txt), skippable with Start or Cross. The game
image has no RAM to spare for a video player, so a small boot program plays the
movie and then loads the game's executable, which sits on the disc as the file
HLGAME.EXE.
The movie is cooked from your install at build time, from the valve.webm the
install names, by the SDK's own movie encoder (psx-str-cook, used as a
library by host/hl-intro-cook). The movie is VP9 video and Opus sound in a
WebM, which the encoder does not read, so the build decodes it first with
ffmpeg, which must be on your PATH: the one outside tool. Without ffmpeg,
or without a startup movie in your install, the build stops with a message
naming it: a disc is never made without the intro by accident. --without-intro
(--no-intro) leaves the stage off on purpose; stack, regress, pgo data
collection and the journeys use such a disc because they replay input from boot.
Nothing derived from the movie is
ever written outside .hlpsx/intro/.
The cook also fits the sound to the player. The CD sound loses 0.9 dB of loudness in the 37.8 to 44.1 kHz conversion on its way to the output (the level assumes the SPU main volume at 0x3FFF is applied at unity, as PSX-SPX and DuckStation do), so the cook measures the movie's integrated loudness (EBU R128, in Rust, no external meter), raises the sound by that much before it is encoded, through a look-ahead limiter that holds the stream under -1 dBFS (the movie's own peak is 2.5 dB under full scale, so it does nothing here). It also starts the sound 24 sectors (160 ms) into the stream, later than the encoder would, which is the time the picture waits for its last sector and for the player's five VBlanks of decoder headroom, so that sound and picture meet.
Open dist/hl-psx.cue in PSoXide or another compatible PlayStation emulator,
or use a suitable development or homebrew loader on original hardware.
The generated image does not include a licensed Sony system area. Hardware boot methods may require an appropriate loader or a separately supplied system area.
| Input | Action |
|---|---|
| Left stick / D-pad | Move |
| Right stick | Look |
| Cross | Jump |
| Triangle | Duck |
| Square | Use |
| R2 | Primary attack |
| L2 | Secondary attack |
| Circle | Reload |
| R1 / L1 | Next / previous weapon |
| L3 | Flashlight |
| Start / Select | Pause |
In menus, use the D-pad to navigate, Cross or Start to confirm, and Circle or Select to go back.
cargo hl-build check # locate and validate Half-Life
cargo hl-build sdk # hydrate the pinned PSoXide SDK
cargo hl-build assets # recook all derived assets
cargo hl-build models # recook and audit models
cargo hl-build audit # audit map and transition residency
cargo hl-build compile # rebuild the PS1 executable
cargo hl-build pack # rebuild the executable and disc
cargo hl-build install --games-dir "DESTINATION_FOLDER" # build and copy
cargo hl-build regress --psoxide "PATH_TO_PSOXIDE" # test matrix
cargo hl-build ram # free RAM, and where the rest went
cargo hl-build stack # stack watermarks and bound against game/stack-reserve
cargo hl-build pgo --tape "RECORDING.pxtape" # profile-guided disc
cargo hl-build --help # show every optionBefore pgo or regress, set HLPSX_FRONTEND to the retained emulator
frontend and HLPSX_FRONTEND_SHA256 to its verified build receipt's digest.
Both commands check that artifact before changing build or profile outputs.
Use the same verified frontend for every paired measurement. The driver
never builds an emulator frontend.
pgo builds the disc twice. The first build replays a PSoXide input recording
in the retained emulator, which counts every instruction the game executes;
the second is compiled around those counts. On the chapter-two recording it
is 6% faster than pack, and 4% faster on a route the recording never
visits. It takes about four minutes. It also writes the profile and the
inlining threshold it linked at to game/pgo/. The threshold comes from the SDK's
psoxide-pgo ladder: it finds the highest thresholds on a 50-unit grid (1000 down to
250) whose link keeps game/ram-budget's floor and leaves a safe stack, meaning at
least 24,580 B between .bss and the initial stack pointer (the deepest stack the
shipping link can reach, 19,664 B by cargo hl-build stack, plus a 25% margin;
game/stack-reserve, 25 KiB, alone covers it), then benches the four highest
distinct images with scripts/pgo-rung-bench.sh (an I-cache layout collected on each,
then c0a0, c4a3 and the Hazard Course chain) and ships the best by geometric mean,
ties going to more free RAM. A candidate more than 1% under the scores in
game/pgo/bench-scores.txt (the build being replaced) on any window is not eligible.
The per-rung table goes to game/pgo/ladder.txt; quote it in the commit message.
HLPSX_LADDER_CANDIDATES=1 takes the highest fit with no bench, for quick local runs
(the full ladder costs about four layout collections and benches). The free RAM
pgo prints for the rung it ships is measured on the link that ships, and the build
stops with both figures if the shipped link leaves a different amount. Plain builds
link at exactly the committed threshold and fail, naming the stale profile, if that
no longer links with a safe stack.
The profiling build
itself links with a smaller stack reserve than the shipped one (it only runs
on the tapes), shrinking it by whatever its link overflows RAM by, down to the
deepest stack the profiling tapes have written (17,760 B) plus a 2 KB margin,
rounded up to 256 B (0x4E00). It also sizes its map staging window and arena
for the maps the profiling tapes load (PGO_COLLECT_MAPS in
host/hl-build/main.rs: maps 6, 7, 9 and 10 for the chapter-two and chapter-three
recordings) instead of the largest map; set HLPSX_COLLECT_MAPS=N,N,... to
profile a recording that visits others. Every other build links with
that committed profile, because HL-PSX no longer fits in RAM without one, so
commit game/pgo/ after a pgo run to make it the default.
Add --polls FROM..TO after a --tape, the gameplay window of that recording
in port-1 polls (1200..5900 for the chapter-two one), and pgo also collects an
instruction-cache layout: it counts every instruction word the window runs and
saves that as game/pgo/hl-psx.layout. The R3000's 4 KB instruction cache is
direct-mapped, so which functions share a cache set decides how often hot code
evicts itself. Every later build places the functions with that layout and
links twice (the code is identical, only its addresses move); a layout that no
longer binds to the code fails the build, naming the unbound functions (the SDK's
psoxide-pgo place gate: 98% of the profile bound and no single function over 1%
left out). Collect it again whenever the profile is. The shipped profile has none: a layout from the chapter-two
tape alone made c1a2b 14% slower when it bound, so do not pass --polls unless
the layout is collected over several maps.
scripts/collect-layout.sh MAP... collects the same layout from scripted maps instead of a
tape (all maps in one layout, so none is favoured); see the header of the script. Redo it
after any code change or pgo run: a layout that no longer binds fails the build.
--script PLAY_ORDER:POLLS (repeatable, with HLPSX_COLLECT_MAPS set to the
maps' room ids so the collect build holds them) profiles a map entered through
the title menu with controller pulses, for that many port-1 polls, beside or
instead of a tape. The recipe the shipped profile came from:
HLPSX_COLLECT_MAPS=0,6,7,9,10,20,94 cargo hl-build pgo \
--tape chapter-two.pxtape --script 0:3400 --script 6:3400 \
--script 20:3400 --script 94:3400pgo keeps only the hottest functions of what it collected (the ones holding
750/1000 of the samples outside the CD and loader code, HLPSX_PGO_COVERAGE to
change it): everything it does not name stays small, and the unpruned profile
grew .text by 47 KB for +19..29% frame rate where this one costs about 1 KB
for +7..16%. The ladder never picks a rung under
game/ram-budget's floor, so raising the floor reserves RAM for unmerged work and
buys back less inlining.
HL_DIR, PSOXIDE, and GAMES_DIR are accepted as environment defaults.
Normal builds hydrate the exact SDK, emulator support crates, and editor/engine
revisions in components.lock.json, verifying imported file hashes before reuse.
The SDK helper dependencies resolve the same SDK revision as that lock. Source owners are
the SDK and
the editor/engine. Contributors
can test a bootstrapped editor checkout with
--psoxide "PATH_TO_PSOXIDE_EDITOR"; an SDK-only checkout does not contain
the required engine/cookers. Such overrides change the effective build input
and must be revalidated. The standalone emulator is maintained in
PSoXide-emulator.
HL-PSX reshapes GoldSrc data around the original console rather than treating the PlayStation as a smaller PC:
- GoldSrc BSP visibility and room-local streaming keep world data bounded.
- World, brush, actor, and viewmodel projection use the Geometry Transformation Engine.
- Textures are converted into compact PlayStation-native pages and managed through explicit VRAM checkpoints.
- Animated models use map-local clip sets and fixed-point bone palettes.
- Maps, models, dialogue, sprites, and sound banks are streamed from CD as needed.
- A sector-aware packing policy compresses a chunk only when it saves disc sectors and passes its runtime-capacity checks.
- Build-time audits cover model RAM, animation mappings, entity support, transition residency, texture capacity, and disc packing.
The deterministic regression suite combines fixed visual probes, recorded input routes, frame telemetry, and repeat renders. Original hardware remains the final authority for timing, audio, controller, and CD-loading behaviour.
| Path | Contents |
|---|---|
game/ |
The no_std PlayStation game crate |
host/hl-build/ |
End-to-end build orchestration (cargo hl-build), its own workspace |
host/hl-content/ |
Menu, audio, sprite, and manifest compiler |
host/hl-bsp/ |
GoldSrc BSP and studio-model cooker |
intro/ |
The disc's boot program: startup movie, then loads the game (own workspace) |
host/hl-intro-cook/ |
Encodes the install's startup movie for intro/ |
host/hl-logic-tests/ |
Host-side gameplay and entity tests |
shared/hl-format/ |
Formats shared by host tools and the game |
regression/ |
Deterministic emulator scenarios and expectations |
Useful source checks for contributors:
bash scripts/check-source-only.sh
cargo fmt --manifest-path host/hl-build/Cargo.toml --package hl-psx-build -- --check
cargo test --manifest-path host/hl-build/Cargo.toml --locked
cargo test --manifest-path host/hl-bsp/Cargo.toml --locked
cargo test --manifest-path host/hl-content/Cargo.toml --locked
cargo test --manifest-path host/hl-logic-tests/Cargo.toml --locked
cargo test --manifest-path shared/hl-format/Cargo.tomlThe full content and hardware validation passes require a local Half-Life installation and a suitable PSoXide or PlayStation test setup.
Code that the project author is entitled to license is offered under GPL-2.0-or-later. The project also contains an attributed adaptation of Quake's GPL-licensed recursive hull trace, links to PSoXide's GPL-2.0-or-later SDK, and includes compatibility code informed by Valve's public Half-Life 1 SDK.
No original or converted Valve binary game assets are tracked or distributed. The project licence does not grant rights in Valve, Sony, or other third-party names or material. Half-Life is a trademark of Valve Corporation. PlayStation is a trademark or registered trademark of Sony Interactive Entertainment Inc. HL-PSX is unofficial and is not affiliated with or endorsed by Valve or Sony.
See LICENSING.md for the complete distribution policy and primary licence links.
Source snapshot 2026.09.05.1 removes two unused renderer experiments. The previous snapshot improved actor depth ordering and rectangular wall grids. See the changelog for details and download availability.